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