Add LumaGuide text-to-histogram regressor, test prompts, and model card

README.md

@@ -0,0 +1,73 @@
+---
+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}
+}
+```

regressor.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f51ba77bf5a702e461ee21ba650b79ebb4d5c30a2ee0e3056329a757038d05e8
+size 1086829

test_prompts.csv

@@ -0,0 +1,101 @@
+prompt,width,height
+"A skier prepares at the top of a glacier as the sun rises, ice glittering with morning light.",512,512
+"A medieval castle catches the first sunrise on its highest tower, the courtyard still in deep shadow.",512,512
+"A heron stands in marsh water at golden hour, plumage backlit and translucent against bright water.",512,512
+"Dusk above clouds from an airplane window, tops of clouds glowing pink against a deep blue stratosphere.",512,512
+"A camel caravan crosses sand dunes at sunset, riders silhouetted against blazing sky.",512,512
+"A monastery on a cliff at sunset, prayer flags fluttering in golden light against deep mountain shadow.",512,512
+"A horseman gallops along a coastline at golden hour, spray and dust catching the low sun.",512,512
+"A full moon rises over a calm sea, casting a brilliant silver path across the water.",512,512
+"A lighthouse at midnight, brilliant sweeping beam cuts through fog and rain.",512,512
+"A cruise ship lit up at sea at night, every porthole and deck blazing against pitch black ocean.",512,512
+"An astronomer at a dark-sky preserve, red headlamp barely illuminating telescope under starlight.",512,512
+"A Japanese pagoda illuminated at night, surrounding garden in deep shadow.",512,512
+"A coal-burning kiln at night, brilliant orange flame visible through the kiln door, smoke against black sky.",512,512
+"A surgical theater with overhead operating lights blazing white, surrounding room in shadow.",512,512
+"A dim bar with neon signs in the windows, single bartender backlit against mirrored shelf.",512,512
+A gallery of medieval armor lit by single spotlights against black walls.,512,512
+A church confessional booth with light streaming through a thin lattice screen.,512,512
+"A school gymnasium with overhead lights blazing onto wooden floor, basketball court empty.",512,512
+"A foundry pour, molten metal glowing intensely white-orange spilling into a casting mold.",512,512
+"A coal-fired power plant at night, smokestacks lit by warning lights against black smoke.",512,512
+"A laser cutter at work in a workshop, brilliant red beam cutting through metal sheet.",512,512
+"A precision machining shop, single overhead lamp directly illuminating a lathe.",512,512
+"A fireworks finale over a harbor, bursts illuminating water and waterfront buildings.",512,512
+"A formula one car at night under track floodlights, brake discs glowing red-hot.",512,512
+"A cherry blossom street at evening, lanterns lighting petals against dusk sky.",512,512
+A 24-hour donut shop window glowing warmly on an empty late-night street.,512,512
+"An outdoor cafe at twilight, candles on each table glowing under string lights overhead.",512,512
+"A medieval cobbled street with hanging lanterns at dusk, warm pools of light at intervals.",512,512
+"A frozen lake at noon, sun reflected in dazzling pinpricks across the ice surface.",512,512
+"A car showroom with high-end vehicles, polished bodies reflecting overhead bright lights.",512,512
+"Frost crystals on a window pane backlit by morning sun, intense sparkling pattern.",512,512
+"A wet seal on a rock catching sunset, water on fur creating brilliant highlights.",512,512
+A water cyclone reaching down to a calm ocean surface in afternoon light.,512,512
+"A glory phenomenon seen from an airplane over clouds, plane shadow surrounded by rainbow rings.",512,512
+"Volcanic lightning over an erupting volcano cone at night, ash plume illuminated.",512,512
+"Ground blizzard at night, headlights revealing dense streaming snowflakes.",512,512
+"A snow-blind tundra at midday, all features bleached out except thin tracks.",512,512
+A school of silver fish flash and glint near the surface of a sunlit reef.,512,512
+A railway station platform with sun streaming through a vaulted iron-and-glass roof.,512,512
+"A planetarium dome from inside during a Saturn close-up, planet glowing on the dome.",512,512
+A puppet theater scene with backlit silhouettes performing on a small bright screen.,512,512
+"A laundromat at midnight, dryers tumbling under harsh fluorescent overhead lights.",512,512
+"A street fortune teller's table at twilight, candles between a crystal ball and tarot cards.",512,512
+A lone phone booth illuminated on a dark country road late at night.,512,512
+An underwater scuba diver's helmet lamp illuminating a small circle of coral reef.,512,512
+"Snow-covered fir forest at sunset, low sun cutting horizontally between trunks.",512,512
+"A bamboo forest at midday, vertical sunbeams cutting downward between green stalks.",512,512
+A mountain cirque at dawn with first light glancing onto snowfields above shadow valleys.,512,512
+"Polar bears on a melting ice floe at midnight sun, golden Arctic light on white fur.",512,512
+"An olive grove on a Mediterranean hillside at noon, dappled shade through silver-green leaves.",512,512
+"A cactus garden in the desert at noon, spines casting tiny shadows on succulent surfaces.",512,512
+"An autumn forest glade at golden hour, fallen yellow leaves catching low sun.",512,512
+"A herd of elephants drinking at a waterhole at golden hour, dust catching low sun.",512,512
+"A snow leopard on a snowy ridge at dusk, fur catching the last warm light.",512,512
+"An eagle's nest on a cliff, parent landing with a fish caught in golden light.",512,512
+A chemical reactor lab with neon glow tubes monitoring reactions in dim room.,512,512
+"A weightlifter at the moment of overhead lift, intense stage lighting on barbell.",512,512
+"An archer at a competition with overhead spots, bowstring tension visible.",512,512
+A boxing knockout punch frozen in mid-impact under arena floodlights.,512,512
+A dressage horse and rider perform under early evening floodlights.,512,512
+Indian temple at twilight with thousands of oil lamps lining stone steps.,512,512
+"A Mexican Day of the Dead altar by candlelight, ofrendas casting flickering shadows.",512,512
+"An Easter sunrise service on a hillside, dawn light over a small congregation.",512,512
+A Burning Man art piece illuminated at dawn against the desert plain.,512,512
+"A Mardi Gras balcony scene at night, beads catching streetlamp light below.",512,512
+London's Tower Bridge at twilight with lights coming on against a deep blue sky.,512,512
+"Hong Kong skyline at night with full neon, junks crossing harbor with strung lights.",512,512
+"Singapore's Gardens by the Bay supertree grove at twilight, illuminated in color.",512,512
+"Rio's Christ the Redeemer at sunrise, statue silhouetted against dawn sky.",512,512
+"Kyoto bamboo forest at dawn, low light filtering through high green stalks.",512,512
+"Iceland's Skogafoss waterfall at midnight sun, falling water glowing.",512,512
+"New Zealand's Milford Sound at dawn, mist rising from black water under cliffs.",512,512
+"China's Great Wall at sunrise, fortifications snaking over hills into golden light.",512,512
+"Spain's La Sagrada Familia at golden hour, intricate stonework throwing complex shadows.",512,512
+"Germany's Neuschwanstein castle at dawn, towers rising above forest mist.",512,512
+Crystal cave with naturally lit selenite formations from above through a sinkhole.,512,512
+A twilight thunderstorm cell with frequent lightning above a desert mesa.,512,512
+A potter's hands shaping a wet clay vessel under workshop task lighting.,512,512
+An old fisherman's hands mending nets in afternoon light on a dock.,512,512
+A samurai's hands gripping a katana in the moonlit doorway of a dojo.,512,512
+A sommelier's hand pouring red wine into a crystal glass under restaurant chandelier.,512,512
+"A tide pool at low tide on a sunny afternoon, anemones and starfish in clear water.",512,512
+"A vintage map shop with tall windows, sun streaming onto a desk piled with charts.",512,512
+"A cave swimming hole at noon, sunbeam from cave opening lighting clear blue water.",512,512
+"A glass-bottomed boat above a coral reef at midday, fish visible swimming below.",512,512
+"A gondola lift cabin ascending at sunset, passengers silhouetted against alpine vista.",512,512
+"A ferris wheel at twilight with each car lit, reflecting in a still lake.",512,512
+A drive-through redwood tunnel with sunbeams between massive trees.,512,512
+"A military convoy at twilight, headlights raised against backdrop of mountains.",512,512
+A submarine surfacing at dawn with sun glancing off conning tower and sea.,512,512
+A polar research station illuminated at midnight in continuous night.,512,512
+"A space telescope launch at golden hour, rocket body glowing orange.",512,512
+"A foley sound stage with arrayed objects under work lights, microphones overhead.",512,512
+"A model train layout under display lighting, miniature buildings lit from within.",512,512
+"A Mars rover at sunset on the red planet, golden dust in low solar light.",512,512
+A futuristic generation ship corridor at night with bioluminescent floor strips.,512,512
+A subterranean lava tube colony with bright settlement lights inside dark cavern.,512,512
+"A starship arrival in port at twilight, observation deck windows glowing yellow.",512,512
+A robot factory assembly line at night with sparks from welding stations along the conveyor.,512,512
+A Dyson swarm sunrise concept: dense ring of solar collectors silhouetted against star.,512,512