resenh 0.1.0__tar.gz

resenh-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# secrets
+.env
+kaggle.json
+*.token
+
+# local-only files
+CLAUDE.md
+Computer Vision Hackathon 2026.pdf
+.remember/
+
+# python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# data, weights, runs
+data/
+weights/
+runs/
+outputs/
+*.pth
+*.pt
+*.safetensors
+*.onnx

resenh-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Sharadh Naidu
+
+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.
+
+Third-party: the Retinexformer architecture (src/resenh/models/retinexformer.py) is
+adapted from https://github.com/caiyuanhao1998/Retinexformer (MIT, Cai et al., ICCV 2023).

resenh-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: resenh
+Version: 0.1.0
+Summary: Robust low-light image restoration and enhancement: classical, deep and adaptive hybrid pipelines.
+Project-URL: Homepage, https://resenh.sharadh.blog
+Project-URL: Source, https://github.com/SharadhNaidu/resen
+Project-URL: Issues, https://github.com/SharadhNaidu/resen/issues
+Project-URL: Weights, https://huggingface.co/SharadhNaiduTrains/resenh
+Author-email: Sharadh Naidu <sharadhanaidu@rvu.edu.in>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: computer-vision,image-enhancement,image-restoration,low-light,retinex
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: pillow>=10.0
+Provides-Extra: app
+Requires-Dist: einops>=0.7; extra == 'app'
+Requires-Dist: gradio>=5.0; extra == 'app'
+Requires-Dist: huggingface-hub>=0.23; extra == 'app'
+Requires-Dist: torch>=2.2; extra == 'app'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: dl
+Requires-Dist: einops>=0.7; extra == 'dl'
+Requires-Dist: huggingface-hub>=0.23; extra == 'dl'
+Requires-Dist: torch>=2.2; extra == 'dl'
+Provides-Extra: eval
+Requires-Dist: einops>=0.7; extra == 'eval'
+Requires-Dist: huggingface-hub>=0.23; extra == 'eval'
+Requires-Dist: lpips>=0.1.4; extra == 'eval'
+Requires-Dist: pyiqa>=0.1.13; extra == 'eval'
+Requires-Dist: scipy>=1.11; extra == 'eval'
+Requires-Dist: torch>=2.2; extra == 'eval'
+Provides-Extra: full
+Requires-Dist: einops>=0.7; extra == 'full'
+Requires-Dist: huggingface-hub>=0.23; extra == 'full'
+Requires-Dist: timm>=1.0; extra == 'full'
+Requires-Dist: torch>=2.2; extra == 'full'
+Requires-Dist: transformers>=4.44; extra == 'full'
+Provides-Extra: train
+Requires-Dist: einops>=0.7; extra == 'train'
+Requires-Dist: huggingface-hub>=0.23; extra == 'train'
+Requires-Dist: imagehash>=4.3; extra == 'train'
+Requires-Dist: lpips>=0.1.4; extra == 'train'
+Requires-Dist: pyiqa>=0.1.13; extra == 'train'
+Requires-Dist: pyyaml>=6.0; extra == 'train'
+Requires-Dist: scipy>=1.11; extra == 'train'
+Requires-Dist: torch>=2.2; extra == 'train'
+Requires-Dist: tqdm>=4.66; extra == 'train'
+Description-Content-Type: text/markdown
+
+# resenh: robust low-light image restoration and enhancement
+
+`resenh` brightens dark, noisy, colour-shifted photos without blowing out lamps, amplifying
+noise or inventing colours. It combines three things:
+
+- **A classical branch:** illumination estimation, Retinex, CLAHE, edge-preserving denoising
+  and colour correction, with every parameter adapted per image.
+- **A deep network:** Retinexformer (ICCV 2023) fine-tuned with the GT-mean loss, taking the
+  classical results as extra inputs.
+- **A quality controller:** checks every candidate output for over-exposure, colour shift,
+  detail loss and noise amplification, and fuses them.
+
+![architecture](https://raw.githubusercontent.com/SharadhNaidu/resen/main/docs/architecture.svg)
+
+**Live demo (runs in your browser):** https://resenh.sharadh.blog
+
+## Install
+
+```bash
+pip install "resenh[dl]"        # classical + deep hybrid (PyTorch)
+pip install resenh              # classical only (numpy + OpenCV, no PyTorch)
+pip install "resenh[app]"       # + Gradio web app
+pip install "resenh[eval]"      # + LPIPS / NIQE metrics
+```
+
+From source: `git clone https://github.com/SharadhNaidu/resen && cd resen && pip install -e ".[dl,app,eval,dev]"`.
+Weights are downloaded and checksum-verified on first use (cached in `~/.cache/resenh`).
+
+## Use
+
+```python
+import resenh
+
+res = resenh.enhance("night.jpg")                 # adaptive hybrid (default)
+resenh.save_image(res.image, "night_enhanced.png")
+res.intermediates["illumination"]                 # every stage is inspectable
+res.decision                                      # controller weights and guard scores
+res.stats, res.params                             # analyzer measurements → chosen parameters
+
+resenh.enhance("night.jpg", mode="classical")     # no deep learning
+resenh.enhance("night.jpg", mode="dl")            # network only
+```
+
+```bash
+resenh enhance night.jpg -o out.png --save-intermediates stages/
+resenh bench --device cpu                          # latency at ~1 MP
+resenh app                                         # web UI at http://localhost:7860
+```
+
+**One command with Docker:** `docker build -t resenh . && docker run -p 7860:7860 resenh`
+
+## Results
+Full tables with all metrics and 95% bootstrap CIs are in
+[`eval_P1_T01.md`](https://github.com/SharadhNaidu/resen/blob/main/eval_P1_T01.md). The ablation is in [`docs/ablation.md`](https://github.com/SharadhNaidu/resen/blob/main/docs/ablation.md)
+and the failure analysis in [`docs/failures.md`](https://github.com/SharadhNaidu/resen/blob/main/docs/failures.md).
+
+**Protocol.**
+- Plain RGB PSNR. No GT-mean correction and no test-time brightness knobs.
+- Checkpoints are fixed in advance (`docs/devlog/protocol-decision.md`); none is selected on
+  the test set.
+- Train and test on the same benchmark only. The LOL-v1/v2 overlap is documented.
+- Our harness reproduces the official Retinexformer checkpoints exactly: 25.15 / 22.79 /
+  25.67 dB, matching the published audit.
+
+## Reproduce
+
+```bash
+pip install -e ".[train,dev]"
+python -m kaggle datasets download -d ohmahler91/lolv1-and-lolv2 -p data/raw/lol --unzip
+python -m kaggle datasets download -d bjzh123/lsrw123 -p data/raw/lsrw --unzip
+python -m kaggle datasets download -d mijancse12/onedrive-1-6-13-2026 -p data/raw/unpaired --unzip
+python training/data_prep.py                 # verify counts, scene-grouped val splits, dedup
+# official Retinexformer weights → weights/retinexformer/ (see src/resenh/models/weights.py)
+bash training/queue.sh                       # fine-tune per benchmark + ablations
+python eval/run_eval.py --methods classical "dl:retinexformer-{bench}" ...
+python eval/make_report.py                   # writes eval_P1_T01.md, docs/ablation.md
+pytest
+```
+
+## Project layout
+
+| Path | What |
+|---|---|
+| `src/resenh/` | the package: `io`, `analysis`, `classical/`, `models/`, `controller`, `pipeline`, `metrics`, `viz`, `cli`, `app` |
+| `training/` | data preparation, training script and GPU queue |
+| `eval/` | evaluation harness and report generator |
+| `docs/` | design document, architecture diagram, ablation, failure analysis, development log |
+| `app/` | Space entry point and example images |
+
+## Credits
+- Retinexformer: Cai et al., ICCV 2023 (MIT), [repo](https://github.com/caiyuanhao1998/Retinexformer).
+- GT-mean loss: Liao et al., ICCV 2025.
+- LIME: Guo et al., TIP 2017.
+- Guided filter: He et al., TPAMI 2013.
+- Evaluation audit: "What Does LOL Measure?", arXiv 2610.38121.
+- Datasets: LOL (Wei et al. 2018), LOL-v2 (Yang et al. 2021), LSRW (Hai et al. 2023),
+  DICM, LIME, MEF, NPE and VV.
+
+## Limitations and responsible use
+See the [design document §8](https://github.com/SharadhNaidu/resen/blob/main/docs/design.md#8-limitations-and-ethics). In short, enhanced
+images can contain hallucinated detail and **must not be used as forensic evidence**. The
+training data is small and mostly indoor.
+
+## License
+MIT

resenh-0.1.0/README.md

@@ -0,0 +1,105 @@
+# resenh: robust low-light image restoration and enhancement
+
+`resenh` brightens dark, noisy, colour-shifted photos without blowing out lamps, amplifying
+noise or inventing colours. It combines three things:
+
+- **A classical branch:** illumination estimation, Retinex, CLAHE, edge-preserving denoising
+  and colour correction, with every parameter adapted per image.
+- **A deep network:** Retinexformer (ICCV 2023) fine-tuned with the GT-mean loss, taking the
+  classical results as extra inputs.
+- **A quality controller:** checks every candidate output for over-exposure, colour shift,
+  detail loss and noise amplification, and fuses them.
+
+![architecture](https://raw.githubusercontent.com/SharadhNaidu/resen/main/docs/architecture.svg)
+
+**Live demo (runs in your browser):** https://resenh.sharadh.blog
+
+## Install
+
+```bash
+pip install "resenh[dl]"        # classical + deep hybrid (PyTorch)
+pip install resenh              # classical only (numpy + OpenCV, no PyTorch)
+pip install "resenh[app]"       # + Gradio web app
+pip install "resenh[eval]"      # + LPIPS / NIQE metrics
+```
+
+From source: `git clone https://github.com/SharadhNaidu/resen && cd resen && pip install -e ".[dl,app,eval,dev]"`.
+Weights are downloaded and checksum-verified on first use (cached in `~/.cache/resenh`).
+
+## Use
+
+```python
+import resenh
+
+res = resenh.enhance("night.jpg")                 # adaptive hybrid (default)
+resenh.save_image(res.image, "night_enhanced.png")
+res.intermediates["illumination"]                 # every stage is inspectable
+res.decision                                      # controller weights and guard scores
+res.stats, res.params                             # analyzer measurements → chosen parameters
+
+resenh.enhance("night.jpg", mode="classical")     # no deep learning
+resenh.enhance("night.jpg", mode="dl")            # network only
+```
+
+```bash
+resenh enhance night.jpg -o out.png --save-intermediates stages/
+resenh bench --device cpu                          # latency at ~1 MP
+resenh app                                         # web UI at http://localhost:7860
+```
+
+**One command with Docker:** `docker build -t resenh . && docker run -p 7860:7860 resenh`
+
+## Results
+Full tables with all metrics and 95% bootstrap CIs are in
+[`eval_P1_T01.md`](https://github.com/SharadhNaidu/resen/blob/main/eval_P1_T01.md). The ablation is in [`docs/ablation.md`](https://github.com/SharadhNaidu/resen/blob/main/docs/ablation.md)
+and the failure analysis in [`docs/failures.md`](https://github.com/SharadhNaidu/resen/blob/main/docs/failures.md).
+
+**Protocol.**
+- Plain RGB PSNR. No GT-mean correction and no test-time brightness knobs.
+- Checkpoints are fixed in advance (`docs/devlog/protocol-decision.md`); none is selected on
+  the test set.
+- Train and test on the same benchmark only. The LOL-v1/v2 overlap is documented.
+- Our harness reproduces the official Retinexformer checkpoints exactly: 25.15 / 22.79 /
+  25.67 dB, matching the published audit.
+
+## Reproduce
+
+```bash
+pip install -e ".[train,dev]"
+python -m kaggle datasets download -d ohmahler91/lolv1-and-lolv2 -p data/raw/lol --unzip
+python -m kaggle datasets download -d bjzh123/lsrw123 -p data/raw/lsrw --unzip
+python -m kaggle datasets download -d mijancse12/onedrive-1-6-13-2026 -p data/raw/unpaired --unzip
+python training/data_prep.py                 # verify counts, scene-grouped val splits, dedup
+# official Retinexformer weights → weights/retinexformer/ (see src/resenh/models/weights.py)
+bash training/queue.sh                       # fine-tune per benchmark + ablations
+python eval/run_eval.py --methods classical "dl:retinexformer-{bench}" ...
+python eval/make_report.py                   # writes eval_P1_T01.md, docs/ablation.md
+pytest
+```
+
+## Project layout
+
+| Path | What |
+|---|---|
+| `src/resenh/` | the package: `io`, `analysis`, `classical/`, `models/`, `controller`, `pipeline`, `metrics`, `viz`, `cli`, `app` |
+| `training/` | data preparation, training script and GPU queue |
+| `eval/` | evaluation harness and report generator |
+| `docs/` | design document, architecture diagram, ablation, failure analysis, development log |
+| `app/` | Space entry point and example images |
+
+## Credits
+- Retinexformer: Cai et al., ICCV 2023 (MIT), [repo](https://github.com/caiyuanhao1998/Retinexformer).
+- GT-mean loss: Liao et al., ICCV 2025.
+- LIME: Guo et al., TIP 2017.
+- Guided filter: He et al., TPAMI 2013.
+- Evaluation audit: "What Does LOL Measure?", arXiv 2610.38121.
+- Datasets: LOL (Wei et al. 2018), LOL-v2 (Yang et al. 2021), LSRW (Hai et al. 2023),
+  DICM, LIME, MEF, NPE and VV.
+
+## Limitations and responsible use
+See the [design document §8](https://github.com/SharadhNaidu/resen/blob/main/docs/design.md#8-limitations-and-ethics). In short, enhanced
+images can contain hallucinated detail and **must not be used as forensic evidence**. The
+training data is small and mostly indoor.
+
+## License
+MIT

resenh-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "resenh"
+version = "0.1.0"
+description = "Robust low-light image restoration and enhancement: classical, deep and adaptive hybrid pipelines."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Sharadh Naidu", email = "sharadhanaidu@rvu.edu.in" }]
+keywords = ["low-light", "image-enhancement", "retinex", "computer-vision", "image-restoration"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Image Processing",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "numpy>=1.24",
+  "opencv-python-headless>=4.8",
+  "pillow>=10.0",
+]
+
+[project.optional-dependencies]
+dl = ["torch>=2.2", "einops>=0.7", "huggingface_hub>=0.23"]
+full = ["resenh[dl]", "transformers>=4.44", "timm>=1.0"]
+eval = ["resenh[dl]", "lpips>=0.1.4", "pyiqa>=0.1.13", "scipy>=1.11"]
+app = ["resenh[dl]", "gradio>=5.0"]
+train = ["resenh[eval]", "pyyaml>=6.0", "imagehash>=4.3", "tqdm>=4.66"]
+dev = ["pytest>=8.0", "ruff>=0.5"]
+
+[project.scripts]
+resenh = "resenh.cli:main"
+
+[project.urls]
+Homepage = "https://resenh.sharadh.blog"
+Source = "https://github.com/SharadhNaidu/resen"
+Issues = "https://github.com/SharadhNaidu/resen/issues"
+Weights = "https://huggingface.co/SharadhNaiduTrains/resenh"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/resenh"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.hatch.build.targets.sdist]
+include = ["src/resenh", "tests", "README.md", "LICENSE", "pyproject.toml"]

resenh-0.1.0/src/resenh/__init__.py

@@ -0,0 +1,14 @@
+"""resenh: robust low-light image restoration and enhancement.
+
+>>> import resenh
+>>> result = resenh.enhance("night.jpg")          # adaptive hybrid (classical + deep)
+>>> resenh.save_image(result.image, "night_enhanced.png")
+"""
+
+from resenh.io import ImageInputError, load_image, save_image
+from resenh.pipeline import MODES, EnhanceResult, enhance
+
+__version__ = "0.1.0"
+
+__all__ = ["enhance", "EnhanceResult", "MODES", "load_image", "save_image", "ImageInputError",
+           "__version__"]

resenh-0.1.0/src/resenh/analysis.py

@@ -0,0 +1,120 @@
+"""Image analyzer: measures the input and maps the measurements to enhancement parameters.
+
+This is what makes the pipeline adaptive (no fixed parameters): every classical stage and the
+controller read their settings from :class:`Params`, computed per image from :class:`Stats`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+import cv2
+import numpy as np
+
+LUMA = np.array([0.299, 0.587, 0.114], dtype=np.float32)
+
+
+def luma(img: np.ndarray) -> np.ndarray:
+    return img @ LUMA
+
+
+def noise_sigma(gray: np.ndarray) -> float:
+    """Immerkaer (1996) fast noise estimate on a [0,1] gray image (returns sigma in [0,1] units).
+
+    Uses the Laplacian-difference kernel, which cancels image structure up to 2nd order.
+    """
+    h, w = gray.shape
+    if h < 3 or w < 3:
+        return 0.0
+    k = np.array([[1, -2, 1], [-2, 4, -2], [1, -2, 1]], dtype=np.float32)
+    conv = cv2.filter2D(gray.astype(np.float32), -1, k, borderType=cv2.BORDER_REFLECT)
+    s = np.abs(conv[1:-1, 1:-1]).sum()
+    return float(s * np.sqrt(0.5 * np.pi) / (6.0 * (w - 2) * (h - 2)))
+
+
+@dataclass
+class Stats:
+    mean_luma: float          # global brightness
+    median_luma: float
+    dark_frac: float          # fraction of pixels with luma < 0.1
+    highlight_frac: float     # fraction of pixels with luma > 0.95 (lamps, signs)
+    noise_sigma: float        # Immerkaer estimate on the raw input
+    rel_noise: float          # noise relative to brightness (what gets amplified)
+    cast: tuple               # per-channel mean / gray mean (colour cast)
+    cast_strength: float      # max |channel ratio - 1|
+    nonuniformity: float      # std/mean of a heavily blurred luma map (uneven lighting)
+    width: int
+    height: int
+
+    def to_dict(self):
+        return asdict(self)
+
+
+@dataclass
+class Params:
+    is_low_light: bool
+    target_mean: float        # desired output mean luma
+    retinex_gamma: float      # illumination compression; smaller = stronger lift
+    gain_floor: float         # bounds max per-pixel gain (1 / floor)
+    clahe_clip: float
+    denoise_strength: float   # 0 = off, 1 = strong
+    wb_strength: float        # 0 = no white balance, 1 = full gray-world
+    highlight_protect: float  # 0..1 how strongly to keep bright regions
+    dl_weight_hint: float     # prior preference for the network output in the controller
+
+    def to_dict(self):
+        return asdict(self)
+
+
+def analyze(img: np.ndarray) -> Stats:
+    y = luma(img)
+    h, w = y.shape
+    small = cv2.resize(y, (max(8, w // 8), max(8, h // 8)), interpolation=cv2.INTER_AREA)
+    blur = cv2.GaussianBlur(small, (0, 0), sigmaX=max(2.0, min(small.shape) / 8))
+    means = img.reshape(-1, 3).mean(axis=0)
+    gray_mean = float(means.mean()) + 1e-6
+    cast = tuple(float(m / gray_mean) for m in means)
+    sigma = noise_sigma(y)
+    mean_l = float(y.mean())
+    return Stats(
+        mean_luma=mean_l,
+        median_luma=float(np.median(y)),
+        dark_frac=float((y < 0.1).mean()),
+        highlight_frac=float((y > 0.95).mean()),
+        noise_sigma=sigma,
+        rel_noise=float(sigma / max(mean_l, 1e-3)),
+        cast=cast,
+        cast_strength=float(max(abs(c - 1.0) for c in cast)),
+        nonuniformity=float(blur.std() / (blur.mean() + 1e-3)),
+        width=w,
+        height=h,
+    )
+
+
+def _lerp(a, b, t):
+    return a + (b - a) * float(np.clip(t, 0.0, 1.0))
+
+
+def choose_params(s: Stats) -> Params:
+    """Map measurements to parameters. Thresholds were set on LOL train/val, never on test."""
+    is_low = s.mean_luma < 0.35 or s.dark_frac > 0.5
+    darkness = np.clip((0.35 - s.mean_luma) / 0.33, 0.0, 1.0)  # 0 = normal, 1 = near black
+    gamma = _lerp(0.85, 0.45, darkness) if is_low else 0.95
+    gamma = min(0.95, gamma + 0.1 * np.clip(s.nonuniformity - 0.6, 0, 1))  # keep relief
+    denoise = np.clip((s.rel_noise - 0.02) / 0.10, 0.0, 1.0)
+    return Params(
+        is_low_light=bool(is_low),
+        target_mean=0.45 if is_low else max(s.mean_luma, 0.4),
+        retinex_gamma=float(gamma),
+        gain_floor=float(_lerp(0.08, 0.025, darkness)),
+        clahe_clip=float(_lerp(2.5, 1.5, denoise)),  # less local contrast when noisy
+        denoise_strength=float(denoise),
+        wb_strength=float(np.clip((s.cast_strength - 0.05) / 0.25, 0.0, 0.8)),
+        # the spatial mask in protect_highlights localises the effect, so even a tiny lamp
+        # gets full protection (networks trained on LOL hallucinate colour in clipped sources)
+        # strongest for small clipped sources (lamps, signs); large clipped areas (sky,
+        # windows) are left to the network. Thresholds checked on val_b.
+        highlight_protect=float(np.clip((0.08 - s.highlight_frac) / 0.05, 0.0, 1.0))
+        if s.highlight_frac > 1e-5 else 0.0,
+        dl_weight_hint=float(1.0 if is_low else 0.3),
+    )

resenh-0.1.0/src/resenh/app.py

@@ -0,0 +1,113 @@
+"""Gradio web app: upload a low-light photo, see the enhancement and every intermediate stage."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import numpy as np
+
+import resenh
+from resenh.metrics import edge_preservation, gain_matched, noise_ratio
+from resenh.viz import panels
+
+try:  # Hugging Face ZeroGPU: allocate a GPU only for the duration of a call
+    import spaces
+
+    _gpu = spaces.GPU(duration=20)
+except Exception:  # noqa: BLE001 - running locally / CPU / Docker
+    def _gpu(fn):
+        return fn
+
+MODE_MAP = {
+    "Hybrid (adaptive, recommended)": "hybrid",
+    "Deep learning only": "dl",
+    "Classical only": "classical",
+}
+
+EXAMPLES_DIR = Path(os.environ.get("RESENH_EXAMPLES",
+                                   Path(__file__).resolve().parents[2] / "app" / "examples"))
+
+
+@_gpu
+def _run(img, mode, tta):
+    return resenh.enhance(img, mode=mode, tta=tta,
+                          max_side=int(os.environ.get("RESENH_MAX_SIDE", 1280)))
+
+
+def process(img, mode_label, tta):
+    import gradio as gr  # noqa: PLC0415
+
+    if img is None:
+        raise gr.Error("Please upload an image first.")
+    try:
+        x = resenh.load_image(img)
+        res = _run(x, MODE_MAP[mode_label], bool(tta))
+    except resenh.ImageInputError as e:
+        raise gr.Error(str(e)) from e
+    out = res.image
+    ref = gain_matched(x, out)
+    s, p = res.stats, res.params
+    lines = [
+        f"### Result: `{res.mode}` mode" + (f" · model `{res.model}`" if res.model else ""),
+        f"**Time:** {res.timings['total']:.2f}s  ·  **Size:** {s.width}×{s.height}",
+        "",
+        "**Analyzer (input measurements → adaptive parameters)**",
+        f"- brightness {s.mean_luma:.3f}, dark pixels {s.dark_frac:.0%}, "
+        f"highlights {s.highlight_frac:.1%}",
+        f"- noise σ {s.noise_sigma:.4f} (relative {s.rel_noise:.3f}), "
+        f"colour cast {s.cast_strength:.2f}, uneven lighting {s.nonuniformity:.2f}",
+        f"- low-light: **{p.is_low_light}** → Retinex γ {p.retinex_gamma:.2f}, "
+        f"denoise {p.denoise_strength:.2f}, CLAHE clip {p.clahe_clip:.1f}, "
+        f"WB {p.wb_strength:.2f}, highlight protect {p.highlight_protect:.2f}",
+        "",
+        "**Output quality (no reference available)**",
+        f"- noise vs. brightened input: ×{noise_ratio(out, ref):.2f} (lower = cleaner)",
+        f"- edge preservation (EPI): {edge_preservation(out, ref):.3f} (1 = all structure kept)",
+    ]
+    if res.decision:
+        d = res.decision
+        lines += ["", "**Quality controller**",
+                  "- weights: " + ", ".join(f"{k} {v:.2f}" for k, v in d["weights"].items()),
+                  "- guard penalties: " + ", ".join(f"{k} {v:.2f}"
+                                                   for k, v in d["penalties"].items())]
+        lines += [f"- ⚠ {n}" for n in d["notes"]]
+    gallery = [((np.clip(im, 0, 1) * 255).astype(np.uint8), lab)
+               for im, lab in panels(res.intermediates, x, out)]
+    out_u8 = (np.clip(out, 0, 1) * 255 + 0.5).astype(np.uint8)
+    in_u8 = (np.clip(x, 0, 1) * 255 + 0.5).astype(np.uint8)
+    return (in_u8, out_u8), out_u8, gallery, "\n".join(lines)
+
+
+def build():
+    import gradio as gr  # noqa: PLC0415
+
+    examples = sorted(str(p) for p in EXAMPLES_DIR.glob("*")) if EXAMPLES_DIR.exists() else []
+    with gr.Blocks(title="resenh: low-light enhancement") as demo:
+        gr.Markdown(
+            "# resenh: robust low-light image enhancement\n"
+            "Adaptive hybrid of classical Retinex/CLAHE/edge-preserving denoising and a "
+            "fine-tuned Retinexformer, fused by a quality controller. "
+            "Upload a dark photo (JPEG/PNG)."
+        )
+        with gr.Row():
+            with gr.Column(scale=1):
+                inp = gr.Image(label="Low-light input", type="numpy", image_mode="RGB",
+                               sources=["upload", "clipboard", "webcam"])
+                mode = gr.Radio(list(MODE_MAP), value=list(MODE_MAP)[0], label="Method")
+                tta = gr.Checkbox(label="High quality (×8 self-ensemble, slower)", value=False)
+                btn = gr.Button("Enhance", variant="primary")
+                if examples:
+                    gr.Examples(examples, inputs=inp, label="Examples (unseen test images)")
+            with gr.Column(scale=2):
+                slider = gr.ImageSlider(label="Before / after", type="numpy")
+                out_img = gr.Image(label="Enhanced (download)", type="numpy", format="png")
+        report = gr.Markdown()
+        gallery = gr.Gallery(label="Intermediate stages", columns=4, height="auto")
+        btn.click(process, [inp, mode, tta], [slider, out_img, gallery, report],
+                  concurrency_limit=2)
+    return demo
+
+
+if __name__ == "__main__":
+    build().launch()

resenh-0.1.0/src/resenh/classical/__init__.py

@@ -0,0 +1,55 @@
+"""Classical low-light enhancement branch (adaptive, parameters come from the analyzer)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from resenh.analysis import Params, analyze, choose_params
+from resenh.classical.clahe import clahe_luma
+from resenh.classical.color import gray_world, match_exposure, protect_highlights
+from resenh.classical.denoise import denoise, denoise_measured
+from resenh.classical.illumination import estimate_illumination, reflectance, retinex_enhance
+
+__all__ = ["enhance_classical"]
+
+
+def enhance_classical(img: np.ndarray, params: Params | None = None,
+                      denoise_method: str = "guided",
+                      disable: frozenset[str] = frozenset()) -> tuple[np.ndarray, dict]:
+    """Run the classical branch. Returns (output, intermediates).
+
+    Stage order: denoise (before any gain, so noise is not amplified) -> illumination
+    estimation -> Retinex/LIME lift -> CLAHE on luma -> gray-world WB -> exposure match ->
+    highlight protection. ``disable`` names stages to skip (for ablation): any of
+    {"denoise", "retinex", "clahe", "wb", "exposure", "highlights"}.
+    """
+    if params is None:
+        params = choose_params(analyze(img))
+    inter: dict[str, np.ndarray] = {}
+    x = img
+    if "denoise" not in disable:
+        x = denoise(x, params.denoise_strength, denoise_method)
+    inter["denoised"] = x
+    illum = estimate_illumination(x)
+    inter["illumination"] = illum
+    inter["reflectance"] = reflectance(x, illum)
+    if "retinex" not in disable:
+        x, applied = retinex_enhance(x, illum, gamma=params.retinex_gamma,
+                                     floor=params.gain_floor)
+        inter["retinex"] = x
+        inter["gain_map"] = np.clip(1.0 / applied / 25.0, 0, 1)
+        if "denoise" not in disable:
+            # residual noise is amplified by the gain: re-estimate it and filter adaptively
+            x = denoise_measured(x)
+            inter["post_denoised"] = x
+    if "clahe" not in disable:
+        c = clahe_luma(x, params.clahe_clip)
+        x = (0.5 * x + 0.5 * c).astype(np.float32)  # half-strength: CLAHE alone over-sharpens noise
+        inter["clahe"] = c
+    if "wb" not in disable:
+        x = gray_world(x, params.wb_strength)
+    if "exposure" not in disable:
+        x = match_exposure(x, params.target_mean)
+    if "highlights" not in disable:
+        x = protect_highlights(x, img, params.highlight_protect)
+    return np.clip(x, 0.0, 1.0).astype(np.float32), inter