hintauc 0.1.0__tar.gz

hintauc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 xuekt98
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hintauc-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: hintauc
+Version: 0.1.0
+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"
+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)](#installation)
+[![PyTorch 2.5](https://img.shields.io/badge/PyTorch-2.5-ee4c2c)](#installation)
+[![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"**
+(Koki Madono, Yuan Mingcheng, Edgar Simo-Serra — IEEE Transactions on Visualization and Computer Graphics, 2026).
+
+![Deterministic hint generation pipeline](assets/readme/dht_pipeline.png)
+
+## Highlights
+
+- **Deterministic hints (DHT).** The same illustration always yields the same scribble and dot hints, so
+  hint-based colorization methods can be compared without random-seed luck.
+- **Hint-AUC.** One number that scores a model over the *whole* range of hint ratios, from no hints to fully hinted.
+- **DetFill.** A pixel-space diffusion colorization model trained with these hints, with all checkpoints released.
+- **Reproducible.** Tables are rebuilt from released metric files, every experiment can be re-run on example images
+  with one command, and the paper's key figure is reproduced end-to-end by a single script.
+
+## News
+
+- **2026-09** — Code, checkpoints, data and the full reproduction package are public. The paper is accepted at IEEE TVCG.
+
+## Installation
+
+```bash
+pip install git+https://github.com/MADONOKOUKI/DetFill-with-DHT.git
+# with the perceptual metrics (LPIPS / OpenCLIP / DINOv2 / DreamSim):
+pip install "hintauc[perceptual] @ git+https://github.com/MADONOKOUKI/DetFill-with-DHT.git"
+```
+
+For training or inference with DetFill, or for reproducing the paper, use the conda environment
+`replicability/environment.yml` (Python 3.9, PyTorch 2.5.1, CUDA 12.4; it also runs on CPU).
+
+## 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)).
+
+## Model zoo
+
+| Model | Hints | Base channels | Trained on | Download |
+|---|---|---|---|---|
+| DetFill (paper) | scribble | 96 | Danbooru2021 | [v1.0](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.0) `detfill_scribble_illust_200ep.pth` (1.08 GB) |
+| DetFill (paper) | dot | 64 | Danbooru2021 | [v1.0](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.0) `detfill_dot_illust_200ep.pth` (0.48 GB) |
+| DetFill, DanbooRegion hints | scribble | 96 | Danbooru2021 | [v1.1](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.1) |
+| DetFill, SLIC hints | scribble | 96 | Danbooru2021 | [v1.1](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.1) |
+| DetFill, natural images | scribble / dot | 96 | ImageNet subset | [v1.2](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.2) |
+| Diffusart retrained with our hints | scribble / dot | — | Danbooru2021 | [v1.2](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.2) |
+| DetFill, channel ablation | scribble | 32 / 64 | Danbooru2021 | [legacy-2024](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/legacy-2024) |
+| DetFill, 2024 submission | scribble / dot | 64 | Danbooru2021 / ImageNet | [legacy-2024](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/legacy-2024) |
+
+Data: the stored hint maps of the 3,000 test images (v1.0), the test-split line art from the three extractors, the
+alternative-segmenter hint maps, the example bundle and the user-study stimuli (v1.3). Every file with size and
+SHA-256: [checkpoints/README.md](checkpoints/README.md).
+
+## Reproducing the paper
+
+All scripts fetch what they need from the releases (SHA-256 verified). Requirements: Linux, Miniconda, ~10 GB of disk,
+an NVIDIA GPU (CPU works but is slow).
+
+| Goal | Command (no arguments) | Time |
+|---|---|---|
+| **Fig. 9** end to end (the Replicability-Stamp script) | `bash replicability/run.sh` | GPU ≈ 3 min, CPU ≈ 30 min |
+| **Every table** rebuilt from the released metric files | `python reproduce/scripts/A1_tables_from_released_metrics.py` (322/324 cells match)<br>`python reproduce/scripts/A2_userstudy_glmm.py` (all values match) | < 2 min, CPU |
+| **Every experiment** re-run on 12 example illustrations | `bash reproduce/examples/run_examples.sh` | smoke ≈ 5 min, default ≈ 1 h, full = hours |
+| **A whole table row** on the 3,000 test images | `DATA_ROOT=… bash reproduce/scripts/run_hauc_pipeline.sh` | ≈ 14 GPU-h per row |
+| **Training** from scratch | `bash reproduce/scripts/B9_train_detfill.sh` | days, 10 GPUs |
+
+Results are compared automatically with the paper's numbers, the paper's archived images of the same examples and the
+authors' reference run. Guide, coverage table and the list of what is bit-exact and what is not:
+[reproduce/README.md](reproduce/README.md). Background on every component: [detail_explanation.md](detail_explanation.md).
+
+## Added features (since the paper) for improving our library
+
+- `hintauc` pip library and command line (hint generation, the seven metrics, Hint-AUC).
+- Dependency-free, bit-exact longest path `path_method="geodesic"`; dot options `medoid` / `mean` / `nearest_mean`;
+  region tie-breaking `tie_break="stable"`.
+- Protocol switch `hint_order: area | label` (Table II vs. Table III) in the DetFill loader; training option `include_full_hint`.
+- CPU inference, a flat user-configurable data layout, deterministic region-id colours, other segmenters in the generator.
+- The replicability script, the reproduction package and the additional releases (v1.1–v1.3, legacy-2024).
+
+Small documented differences between the paper's text and the released code/data are listed in
+[detail_explanation.md](detail_explanation.md#changes-relative-to-the-paper).
+
+## Repository structure
+
+```
+replicability/     one-command reproduction of Fig. 9
+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/       inventory of all released files with hashes
+assets/            images for this page; representative image for the Replicability Stamp
+```
+
+## Citation
+
+```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}
+}
+```
+
+## License and acknowledgements
+
+MIT License; third-party components 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.

hintauc-0.1.0/README.md

@@ -0,0 +1,131 @@
+# 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)](#installation)
+[![PyTorch 2.5](https://img.shields.io/badge/PyTorch-2.5-ee4c2c)](#installation)
+[![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"**
+(Koki Madono, Yuan Mingcheng, Edgar Simo-Serra — IEEE Transactions on Visualization and Computer Graphics, 2026).
+
+![Deterministic hint generation pipeline](assets/readme/dht_pipeline.png)
+
+## Highlights
+
+- **Deterministic hints (DHT).** The same illustration always yields the same scribble and dot hints, so
+  hint-based colorization methods can be compared without random-seed luck.
+- **Hint-AUC.** One number that scores a model over the *whole* range of hint ratios, from no hints to fully hinted.
+- **DetFill.** A pixel-space diffusion colorization model trained with these hints, with all checkpoints released.
+- **Reproducible.** Tables are rebuilt from released metric files, every experiment can be re-run on example images
+  with one command, and the paper's key figure is reproduced end-to-end by a single script.
+
+## News
+
+- **2026-09** — Code, checkpoints, data and the full reproduction package are public. The paper is accepted at IEEE TVCG.
+
+## Installation
+
+```bash
+pip install git+https://github.com/MADONOKOUKI/DetFill-with-DHT.git
+# with the perceptual metrics (LPIPS / OpenCLIP / DINOv2 / DreamSim):
+pip install "hintauc[perceptual] @ git+https://github.com/MADONOKOUKI/DetFill-with-DHT.git"
+```
+
+For training or inference with DetFill, or for reproducing the paper, use the conda environment
+`replicability/environment.yml` (Python 3.9, PyTorch 2.5.1, CUDA 12.4; it also runs on CPU).
+
+## 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)).
+
+## Model zoo
+
+| Model | Hints | Base channels | Trained on | Download |
+|---|---|---|---|---|
+| DetFill (paper) | scribble | 96 | Danbooru2021 | [v1.0](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.0) `detfill_scribble_illust_200ep.pth` (1.08 GB) |
+| DetFill (paper) | dot | 64 | Danbooru2021 | [v1.0](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.0) `detfill_dot_illust_200ep.pth` (0.48 GB) |
+| DetFill, DanbooRegion hints | scribble | 96 | Danbooru2021 | [v1.1](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.1) |
+| DetFill, SLIC hints | scribble | 96 | Danbooru2021 | [v1.1](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.1) |
+| DetFill, natural images | scribble / dot | 96 | ImageNet subset | [v1.2](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.2) |
+| Diffusart retrained with our hints | scribble / dot | — | Danbooru2021 | [v1.2](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/v1.2) |
+| DetFill, channel ablation | scribble | 32 / 64 | Danbooru2021 | [legacy-2024](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/legacy-2024) |
+| DetFill, 2024 submission | scribble / dot | 64 | Danbooru2021 / ImageNet | [legacy-2024](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases/tag/legacy-2024) |
+
+Data: the stored hint maps of the 3,000 test images (v1.0), the test-split line art from the three extractors, the
+alternative-segmenter hint maps, the example bundle and the user-study stimuli (v1.3). Every file with size and
+SHA-256: [checkpoints/README.md](checkpoints/README.md).
+
+## Reproducing the paper
+
+All scripts fetch what they need from the releases (SHA-256 verified). Requirements: Linux, Miniconda, ~10 GB of disk,
+an NVIDIA GPU (CPU works but is slow).
+
+| Goal | Command (no arguments) | Time |
+|---|---|---|
+| **Fig. 9** end to end (the Replicability-Stamp script) | `bash replicability/run.sh` | GPU ≈ 3 min, CPU ≈ 30 min |
+| **Every table** rebuilt from the released metric files | `python reproduce/scripts/A1_tables_from_released_metrics.py` (322/324 cells match)<br>`python reproduce/scripts/A2_userstudy_glmm.py` (all values match) | < 2 min, CPU |
+| **Every experiment** re-run on 12 example illustrations | `bash reproduce/examples/run_examples.sh` | smoke ≈ 5 min, default ≈ 1 h, full = hours |
+| **A whole table row** on the 3,000 test images | `DATA_ROOT=… bash reproduce/scripts/run_hauc_pipeline.sh` | ≈ 14 GPU-h per row |
+| **Training** from scratch | `bash reproduce/scripts/B9_train_detfill.sh` | days, 10 GPUs |
+
+Results are compared automatically with the paper's numbers, the paper's archived images of the same examples and the
+authors' reference run. Guide, coverage table and the list of what is bit-exact and what is not:
+[reproduce/README.md](reproduce/README.md). Background on every component: [detail_explanation.md](detail_explanation.md).
+
+## Added features (since the paper) for improving our library
+
+- `hintauc` pip library and command line (hint generation, the seven metrics, Hint-AUC).
+- Dependency-free, bit-exact longest path `path_method="geodesic"`; dot options `medoid` / `mean` / `nearest_mean`;
+  region tie-breaking `tie_break="stable"`.
+- Protocol switch `hint_order: area | label` (Table II vs. Table III) in the DetFill loader; training option `include_full_hint`.
+- CPU inference, a flat user-configurable data layout, deterministic region-id colours, other segmenters in the generator.
+- The replicability script, the reproduction package and the additional releases (v1.1–v1.3, legacy-2024).
+
+Small documented differences between the paper's text and the released code/data are listed in
+[detail_explanation.md](detail_explanation.md#changes-relative-to-the-paper).
+
+## Repository structure
+
+```
+replicability/     one-command reproduction of Fig. 9
+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/       inventory of all released files with hashes
+assets/            images for this page; representative image for the Replicability Stamp
+```
+
+## Citation
+
+```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}
+}
+```
+
+## License and acknowledgements
+
+MIT License; third-party components 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.

hintauc-0.1.0/hintauc/__init__.py

@@ -0,0 +1,66 @@
+"""hintauc — Deterministic region-based hint generation (DHT) and Hint-AUC
+evaluation for line-art colorization.
+
+Library form of the method proposed in
+"Hint-AUC: Deterministic Region-based Hint Generation for Line Art
+Colorization Evaluation" (Madono, Mingcheng, Simo-Serra).
+
+Quick start
+-----------
+>>> import hintauc
+>>> hints = hintauc.generate_hints("illustration.png")       # 1. hints
+>>> color, mask = hints.at_ratio(0.10, hint_type="scribble") # top-10% regions
+>>> hints.save("out/illustration")                           # canonical files
+
+>>> ev = hintauc.Evaluator(metrics=("mse", "psnr", "ssim", "lpips"))
+>>> scores = ev("colorized.png", "ground_truth.png")         # 2. evaluation
+>>> auc = hintauc.hint_auc({0.0: 0.44, 0.01: 0.33, 0.03: 0.27,
+...                         0.05: 0.24, 0.10: 0.20, 0.25: 0.15,
+...                         0.50: 0.12, 1.00: 0.10})
+"""
+
+from .longest_path import geodesic_longest_path
+from .hints import (
+    DEFAULT_HINT_SIZE,
+    FELZENSZWALB_PARAMS,
+    HintResult,
+    generate_hints,
+    region_ids,
+    segment_regions,
+)
+from .metrics import (
+    DEFAULT_METRICS,
+    LOWER_IS_BETTER,
+    Evaluator,
+    evaluate_dirs,
+    evaluate_pair,
+)
+from .auc import (
+    DEFAULT_ALPHAS,
+    evaluate_hint_curve,
+    hint_auc,
+    hint_auc_table,
+    trapz,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_ALPHAS",
+    "DEFAULT_HINT_SIZE",
+    "DEFAULT_METRICS",
+    "FELZENSZWALB_PARAMS",
+    "LOWER_IS_BETTER",
+    "Evaluator",
+    "HintResult",
+    "evaluate_dirs",
+    "evaluate_hint_curve",
+    "evaluate_pair",
+    "generate_hints",
+    "hint_auc",
+    "hint_auc_table",
+    "region_ids",
+    "segment_regions",
+    "trapz",
+    "__version__",
+]

hintauc-0.1.0/hintauc/auc.py

@@ -0,0 +1,73 @@
+"""Hint-AUC: integrate per-ratio metric scores over the hint-ratio grid.
+
+Port of ``evaluation/calc_hint_auc.py``: plain trapezoidal integration
+of metric(alpha) over alpha in [0, 1] (the alpha range has length 1, so the
+integral equals the range-normalized value).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Mapping, Optional, Sequence
+
+#: the paper's front-loaded hint-ratio grid
+DEFAULT_ALPHAS = (0.00, 0.01, 0.03, 0.05, 0.10, 0.25, 0.50, 1.00)
+
+
+def trapz(xs: Sequence[float], ys: Sequence[float]) -> float:
+    """Trapezoidal rule (port of calc_hint_auc.trapz)."""
+    if len(xs) != len(ys) or len(xs) < 2:
+        raise ValueError("need >= 2 (x, y) points with matching lengths")
+    area = 0.0
+    for i in range(1, len(xs)):
+        area += (xs[i] - xs[i - 1]) * (ys[i] + ys[i - 1]) / 2.0
+    return area
+
+
+def hint_auc(scores_by_alpha: Mapping[float, float]) -> float:
+    """Hint-AUC of one metric from ``{alpha: score}``.
+
+    >>> hint_auc({0.0: 0.44, 0.01: 0.33, ..., 1.0: 0.10})
+    """
+    xs = sorted(scores_by_alpha)
+    ys = [scores_by_alpha[a] for a in xs]
+    return trapz(xs, ys)
+
+
+def hint_auc_table(
+    metrics_by_alpha: Mapping[float, Mapping[str, float]],
+    metrics: Optional[Sequence[str]] = None,
+) -> Dict[str, float]:
+    """Hint-AUC per metric from ``{alpha: {metric: score}}``."""
+    alphas = sorted(metrics_by_alpha)
+    if metrics is None:
+        metrics = sorted({m for a in alphas for m in metrics_by_alpha[a]})
+    out = {}
+    for m in metrics:
+        out[m] = hint_auc({a: metrics_by_alpha[a][m] for a in alphas})
+    return out
+
+
+def evaluate_hint_curve(
+    preds_by_alpha: Mapping[float, str],
+    gt_dir: str,
+    evaluator=None,
+    metrics: Sequence[str] = ("mse", "psnr", "ssim"),
+    pairing: str = "sorted",
+    limit: int = 0,
+) -> Dict[str, object]:
+    """End-to-end Hint-AUC over per-ratio prediction directories.
+
+    ``preds_by_alpha`` maps each hint ratio alpha to a directory of the
+    colorizations produced with hints at that ratio (paper grid:
+    :data:`DEFAULT_ALPHAS`).  Returns per-alpha mean metrics and the
+    Hint-AUC of every metric.
+    """
+    from .metrics import Evaluator, evaluate_dirs
+
+    ev = evaluator or Evaluator(metrics=metrics)
+    per_alpha: Dict[float, Dict[str, float]] = {}
+    for alpha in sorted(preds_by_alpha):
+        per_alpha[alpha] = evaluate_dirs(
+            preds_by_alpha[alpha], gt_dir, evaluator=ev,
+            pairing=pairing, limit=limit)
+    return {"per_alpha": per_alpha, "hint_auc": hint_auc_table(per_alpha)}

hintauc-0.1.0/hintauc/cli.py

@@ -0,0 +1,84 @@
+"""Command-line interface: ``hintauc generate`` / ``hintauc eval``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(
+        prog="hintauc",
+        description="Deterministic hint generation (DHT) and Hint-AUC evaluation")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    g = sub.add_parser("generate", help="generate deterministic hints for an image")
+    g.add_argument("image", help="input image (ground-truth color image)")
+    g.add_argument("-o", "--out_stem", default=None,
+                   help="output stem (default: <image without extension>)")
+    g.add_argument("--size", type=int, default=64, help="hint resolution (default 64)")
+    g.add_argument("--segmenter", default="felzenszwalb",
+                   choices=["felzenszwalb", "slic", "quickshift"])
+    g.add_argument("--ratio", type=float, default=None,
+                   help="also write hints masked to this hint ratio (0..1)")
+    g.add_argument("--hint_type", default="scribble", choices=["scribble", "dot"])
+    g.add_argument("--path_method", default="filfinder", choices=["filfinder", "geodesic"],
+                   help="longest-path extraction: 'filfinder' (paper) or 'geodesic' (dependency-free, deterministic)")
+    g.add_argument("--tie_break", default="default", choices=["default", "stable"],
+                   help="order of equal-area regions when selecting by --ratio: 'default' (paper: NumPy argsort) or 'stable' (ascending label; version-independent)")
+    g.add_argument("--dot_method", default="medoid", choices=["medoid", "mean", "nearest_mean"],
+                   help="dot placement: 'mean' (paper: truncated mean of the path, may leave the region) or 'medoid' (in-region path pixel nearest to the mean)")
+    g.add_argument("-v", "--verbose", action="store_true")
+
+    e = sub.add_parser("eval", help="evaluate colorization(s) against ground truth")
+    e.add_argument("pred", help="predicted image or directory")
+    e.add_argument("gt", help="ground-truth image or directory")
+    e.add_argument("--metrics", nargs="+",
+                   default=["mse", "psnr", "ssim"],
+                   help="subset of: mse psnr ssim lpips openclip dino dreamsim")
+    e.add_argument("--pairing", default="sorted", choices=["sorted", "name"])
+    e.add_argument("--resize", type=int, default=256)
+    e.add_argument("--device", default=None)
+    e.add_argument("--limit", type=int, default=0)
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "generate":
+        from .hints import generate_hints
+        import cv2
+
+        res = generate_hints(args.image, size=args.size,
+                             segmenter=args.segmenter, verbose=args.verbose,
+                             path_method=args.path_method, dot_method=args.dot_method)
+        stem = args.out_stem or os.path.splitext(args.image)[0]
+        paths = res.save(stem)
+        if args.ratio is not None:
+            color, mask = res.at_ratio(args.ratio, hint_type=args.hint_type, tie_break=args.tie_break)
+            pct = int(round(args.ratio * 100))
+            cv2.imwrite(f"{stem}_{args.hint_type}_col{res.size}_r{pct}.png", color)
+            cv2.imwrite(f"{stem}_{args.hint_type}_mask{res.size}_r{pct}.png", mask)
+            paths[f"ratio_{pct}"] = f"{stem}_{args.hint_type}_*{res.size}_r{pct}.png"
+        info = {"n_regions": res.n_regions(), "failed_regions": res.failed_regions,
+                "path_method": res.path_method, "dot_method": res.dot_method, "outputs": paths}
+        print(json.dumps(info, indent=1))
+        return 0
+
+    if args.cmd == "eval":
+        from .metrics import Evaluator, evaluate_dirs
+
+        ev = Evaluator(metrics=args.metrics, device=args.device, resize=args.resize)
+        if os.path.isdir(args.pred):
+            scores = evaluate_dirs(args.pred, args.gt, evaluator=ev,
+                                   pairing=args.pairing, limit=args.limit)
+        else:
+            scores = ev(args.pred, args.gt)
+        print(json.dumps(scores, indent=1))
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())