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

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:

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

@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}
}