Add model card and usage documentation

README.md

@@ -0,0 +1,94 @@
+---
+license: apache-2.0
+library_name: diffusers
+base_model: black-forest-labs/FLUX.2-klein-4B
+tags:
+- lora
+- image-editing
+- image-to-image
+- relighting
+- shadow-removal
+- trail-photography
+---
+
+# Trail Delighter — FLUX.2 Klein 4B LoRA
+
+This is a source-conditioned LoRA for **FLUX.2 Klein 4B**. It was trained for
+one narrow task: reducing cast shadows, glare, and uneven illumination in
+trail-surface photographs while preserving the camera viewpoint and physical
+scene structure.
+
+It is not a general-purpose shadow-removal model. The training set consists of
+real Chunk 0 trail photographs paired with Qwen/Fal lighting-restoration
+outputs. The model is intended for texture-capture imagery and may perform
+poorly on unrelated photographs.
+
+## Files
+
+- `training/trail_delight_klein4b_highres15.safetensors` — final LoRA
+- `training/checkpoints/` — 125, 250, and 375 step checkpoints
+- `examples/teacher_pairs/original/` — original trail photos
+- `examples/teacher_pairs/qwen_delighted/` — Qwen/Fal teacher outputs
+- `examples/teacher_pairs/klein_lora/` — corresponding Klein LoRA outputs
+
+The base FLUX.2 Klein weights are not included. Download them from the
+upstream model repository separately.
+
+## Inference with Diffusers
+
+```python
+import torch
+from diffusers import Flux2KleinPipeline
+from diffusers.utils import load_image
+
+base = "black-forest-labs/FLUX.2-klein-4B"
+lora = "DirtScan/trail-delighter"
+
+pipe = Flux2KleinPipeline.from_pretrained(base, torch_dtype=torch.float16)
+pipe.load_lora_weights(lora, subfolder="training", adapter_name="trail_delight")
+pipe.set_adapters(["trail_delight"], adapter_weights=[1.0])
+pipe.enable_sequential_cpu_offload(device="cuda")
+pipe.vae.enable_tiling()
+pipe.vae.enable_slicing()
+
+image = load_image("input-trail-photo.png").convert("RGB").resize((768, 448))
+result = pipe(
+    image=image,
+    prompt=(
+        "Edit this trail-surface photograph under neutral soft overcast illumination. "
+        "Remove cast shadows and glare while preserving the exact trail geometry, "
+        "rocks, leaves, markings, materials, and camera viewpoint."
+    ),
+    width=768,
+    height=448,
+    num_inference_steps=4,
+    guidance_scale=1.0,
+).images[0]
+result.save("trail-delighted.png")
+```
+
+For local inference, the final LoRA is small, but the unquantized base model
+is substantially larger than an 8 GB GPU. Sequential CPU offload or a
+compatible quantized runtime may be required.
+
+## Training summary
+
+- Base: FLUX.2 Klein 4B
+- Adapter: LoRA, rank 16
+- Teacher: Qwen Image Edit lighting-restoration via Fal
+- Teacher pairs: 15 real Chunk 0 trail-photo pairs
+- Resolution used for the student run: 768 × 448
+- Final checkpoint: 500 training steps
+
+## Limitations
+
+The adapter can still produce image-to-image hue variation, local texture
+changes, or residual seams when many independently processed views are merged
+into a texture atlas. It should therefore be followed by atlas-level colour
+harmonization and seam-aware blending for 3D texturing.
+
+## License
+
+The adapter is provided under Apache-2.0, subject to the terms of the base
+FLUX.2 Klein model and the rights to the training photographs and teacher
+outputs.