File size: 2,964 Bytes
71d5fe6 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | ---
license: mit
pipeline_tag: text-to-image
library_name: pytorch
tags:
- hdr
- hdr-generation
- diffusion
- guidance
- training-free
- flux
- distribution-shaping
- luminance
base_model:
- black-forest-labs/FLUX.1-dev
base_model_relation: adapter
---
# LumaGuide: text-to-histogram regressor and test prompts
Assets for **LumaGuide: Distribution Shaping for Training-Free HDR Generation in Diffusion Models** (Bowen Chen, Shreshth Saini, Balu Adsumilli, Alan C. Bovik).
- Paper: https://arxiv.org/abs/2607.26237
- Code: https://github.com/shreshthsaini/LumaGuide
- Project page: https://shreshthsaini.github.io/LumaGuide/
LumaGuide is training-free. It steers a pretrained diffusion model at sampling time so that a feature distribution of the output matches a target, using differentiable energy-based guidance. For HDR generation the feature is the PQ-space luminance histogram, matched with a Wasserstein-1 loss back-propagated through the VAE decoder of Flux.1-dev. The diffusion transformer is never trained or modified.
## What is in this repo
| File | Purpose |
| --- | --- |
| `regressor.pt` | Caption-to-histogram regressor: a 3-layer MLP (768 to 256 to 256 to 32, GELU) on the pooled `openai/clip-vit-large-patch14` text embedding, softmax output over 32 PQ-luminance bins. 270,880 parameters, 1.1 MB. This is the default target source for `--target regressor`. |
| `test_prompts.csv` | The 100 HDR test prompts used in the paper, with generation width and height. |
The regressor only provides the target histogram. The guidance itself, the PQ luminance utilities, and the Flux sampler hooks live in the GitHub repo.
## Usage
```bash
git clone https://github.com/shreshthsaini/LumaGuide && cd LumaGuide
pip install -r requirements.txt
huggingface-cli download shreshthsaini/LumaGuide regressor.pt --local-dir .
python lumaguide.py --prompt "A skier at the top of a glacier as the sun rises" \
--target regressor --regressor_ckpt regressor.pt --out out.hdr
```
Or load the checkpoint yourself:
```python
import torch
from huggingface_hub import hf_hub_download
state = torch.load(hf_hub_download("shreshthsaini/LumaGuide", "regressor.pt"), map_location="cpu", weights_only=False)
state["config"] # {'in_dim': 768, 'hidden': 256, 'n_bins': 32}
state["model_state"] # weights for HistRegressor in lumaguide.py
```
Flux.1-dev is downloaded separately from Hugging Face and is gated; accept its license first. It needs about 30 GB of VRAM at 512x512 with LumaGuide's VAE backward pass.
## License
The regressor and prompts are released under MIT. Flux.1-dev is governed by the Black Forest Labs non-commercial license.
## Citation
```bibtex
@article{chen2026lumaguide,
title = {LumaGuide: Distribution Shaping for Training-Free HDR Generation in Diffusion Models},
author = {Chen, Bowen and Saini, Shreshth and Adsumilli, Balu and Bovik, Alan C.},
journal = {arXiv preprint arXiv:2607.26237},
year = {2026}
}
```
|