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
