Make model card visual, clear, and easier to explore

README.md

@@ -6,28 +6,65 @@ base_model:
   - stable-diffusion-v1-5/stable-diffusion-inpainting
 license: creativeml-openrail-m
 tags:
+  - image-editing
+  - local-ai
+  - diffusers
   - clover-image
   - inpainting
   - stable-diffusion
   - coreml
 ---
 
-# Clover Image Tiny Inpaint HQ
 
-Clover Image Tiny Inpaint HQ is the high-quality, context-aware inpainting
-companion to [Clover Image Tiny](https://huggingface.co/neonforestmist/Clover-Image-Tiny).
-It combines the complete Stable Diffusion 1.5 inpainting U-Net with Clover
-Image Tiny's tokenizer, text encoder, VAE, and scheduler.
-This preserves Clover compatibility while replacing the compact inpainting
-denoiser that frequently produced blurry or unrecognizable masked objects.
+# 🍀 Clover Image Tiny Inpaint HQ
 
-The pipeline uses the standard nine-channel inpainting contract:
+### Keep the scene. Change the detail.
 
-```text
-[noisy latent (4), mask (1), masked-image latent (4)]
-```
+**Paint a mask, describe your edit, and give an existing image a new direction.**
+Clover Inpaint HQ is an open-weight AI inpainting model for local image editing with
+Python and Diffusers, with companion Core ML resources for Apple apps.
+
+<p align="center">
+  <a href="https://huggingface.co/spaces/neonforestmist/Clover-Image-Tiny-Demo"><img alt="Try inpainting" src="https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint/resolve/main/assets/links/try-inpainting.svg" height="40"></a>
+  <a href="https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint/tree/main"><img alt="Get the model" src="https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint/resolve/main/assets/links/get-model.svg" height="40"></a>
+  <a href="https://github.com/neonforestmist/Clover-Image-Tiny"><img alt="GitHub source" src="https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint/resolve/main/assets/links/github-source.svg" height="40"></a>
+</p>
+
+## Inpainting example
+
+Want to change just one part of an image? Select that area with a mask and describe what
+belongs there. This published Clover example uses the prompt **“add blue sunglasses.”**
+
+| Original image | Masked edit |
+|:---:|:---:|
+| ![Cat artwork before the sunglasses edit](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint/resolve/3e22009fb6e61944f28b0389f775fc47e2c48724/examples/sunglasses-source.png) | ![Clover inpainting result showing blue sunglasses on the cat](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint/resolve/3e22009fb6e61944f28b0389f775fc47e2c48724/examples/sunglasses-result.png) |
+
+## What you can do
+
+- **Explore a focused change.** Add or replace a detail while keeping the surrounding scene as context.
+- **Control where the edit happens.** A white mask selects the area to regenerate; black selects the area to preserve.
+- **Work locally.** After downloading the model and dependencies, your Python workflow can run offline.
+- **Build an image editor.** Use the standard Diffusers pipeline or the [Core ML companion](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint-CoreML).
+
+For pixel-exact preservation, composite the generated result through the original binary
+mask. The mask and compositing step—not the prompt alone—protect the unedited image.
+
+## A quality-focused companion to Clover
+
+Inpaint HQ uses the **full Stable Diffusion 1.5 inpainting denoiser** with Clover's
+text encoder, tokenizer, VAE, and scheduler. It is a larger model than the compact
+[regular Clover text-to-image checkpoint](https://huggingface.co/neonforestmist/Clover-Image-Tiny). Choose regular Clover to create
+from text, and Inpaint HQ when you already have an image to edit.
 
-## Diffusers example
+On the release's 24-edit held-out evaluation, HQ improved masked prompt alignment by
+**4.8%** and reduced masked target error by **11.1%** versus the previous Clover inpainting
+release. These are evaluation-set results; individual edits still depend on the image,
+mask, and prompt. [See the full quality gate and selection record](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint/blob/main/docs/MODEL_DETAILS.md).
+
+## Run an edit with Python
+
+Install the [project's pinned Python dependencies](https://github.com/neonforestmist/Clover-Image-Tiny#run-clover-locally).
+This example uses an NVIDIA CUDA GPU:
 
 ```python
 import torch
@@ -52,91 +89,37 @@ image = pipe(
 image.save("clover-inpaint.png")
 ```
 
-Recommended interactive defaults are DPM-Solver++, 20 steps, CFG 6.0, and a
-96-pixel context crop. Composite the generated result through the exact binary
-mask when unchanged source pixels must remain byte-for-byte untouched.
+Start with **20 steps**, **guidance 6.0**, and **96 pixels of surrounding context**.
+Use a source image and same-size grayscale mask. Small selections benefit from a
+context crop so the model can see both the edited region and its surroundings.
+To use an already downloaded model offline, pass `local_files_only=True` to
+`from_pretrained`.
 
-## Inpainting example
+<details>
+<summary>Apple silicon and CPU</summary>
 
-This edit starts from the Clover Image Tiny artwork below and uses the prompt
-`add blue sunglasses`. The source and result are included so the masked edit
-can be compared directly.
+For Apple silicon, change `.to("cuda")` to `.to("mps")`. For CPU, use
+`torch_dtype=torch.float32` and `.to("cpu")`; generation is slower. Hardware,
+precision, and dependencies can change the result even with the same seed.
 
-| Source image | Inpainted result |
-|:---:|:---:|
-| ![Cat source before adding sunglasses](examples/sunglasses-source.png) | ![Cat after adding blue sunglasses](examples/sunglasses-result.png) |
-
-## Quality gate
-
-The release was evaluated on 24 deterministic, held-out, human-rated
-InpaintCOCO edits. Every output was also reviewed in three visual contact
-sheets before release.
-
-| Metric | Previous Clover inpaint | HQ release | SD 1.5 inpaint teacher |
-|---|---:|---:|---:|
-| Masked prompt CLIP similarity (higher) | 0.2642 | **0.2768** | 0.2820 |
-| Masked target MAE (lower) | 0.2510 | **0.2231** | 0.2156 |
-| Changed pixels outside the mask | 0 | **0** | 0 |
-
-The HQ release improves prompt alignment by 4.8% and reduces masked target
-error by 11.1% relative to the previous Clover inpainting release. The visual
-gate showed recognizable buses, dogs, trains, furniture, signs, and
-scene-consistent lighting where the compact candidates often collapsed into
-amorphous fills.
-
-## Selection provenance
-
-The release process compared the existing checkpoint, a 30,000-step full-U-Net
-distillation run, two fused context-LoRA refinements, partial weight blends,
-the full Stable Diffusion inpainting reference, and this Clover-component
-hybrid. The 30,000-step and context-LoRA candidates were rejected because they
-did not beat the existing release across both visual and quantitative gates.
-The published HQ architecture was the only Clover-compatible candidate that
-materially improved both prompt alignment and reconstruction.
-
-- Inpainting U-Net revision:
-  `stable-diffusion-v1-5/stable-diffusion-inpainting@8a4288a76071f7280aedbdb3253bdb9e9d5d84bb`
-- Clover components: `neonforestmist/Clover-Image-Tiny`
-- Evaluation dataset: `phiyodr/InpaintCOCO@1ffac84be2dfc5ad9afccad868522fad64457435`
-- Selection platform: Modal H100
-- Evaluation seed: `20260813`
-
-## Core ML and style mixing
-
-The companion iOS resources are published at
-[`neonforestmist/Clover-Image-Tiny-Inpaint-CoreML`](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint-CoreML).
-
-In Diffusers, the published Clover style LoRAs are mechanically compatible
-with this nine-channel U-Net because they modify attention projections only;
-those tensor shapes are unchanged from the four-channel model. They were
-trained for text-to-image, however, so masked-edit quality should be evaluated
-per style. LoRAs that modify the four-channel input convolution are not
-compatible.
-
-Dynamic Core ML loading is a separate deployment capability. The shipping iOS
-inpainting screen currently selects a stateless or chunked U-Net and does not
-enable styles. An adapter-aware stateful nine-channel export can provide up to
-three independently weighted slots, but it must include the matching adapter
-schema and be validated on its target devices. For a stateless deployment,
-fuse a compatible LoRA before conversion.
-
-## Limitations
-
-Small text, hands, faces, exact logos, and masks below latent resolution can
-still fail. Output quality depends on the source, mask, prompt, scheduler,
-guidance, seed, and step count. This release inherits the limitations and
-license obligations of Clover Image Tiny and Stable Diffusion 1.5 inpainting.
-
-## Citation
-
-```bibtex
-@software{lozadaperez2026cloverimagetinyinpaint,
-  author = {Lukas Lozada Perez},
-  title = {Clover Image Tiny Inpaint HQ: Local Context-Aware Image Inpainting},
-  year = {2026},
-  url = {https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint}
-}
-```
+</details>
+
+## Styles and Apple devices
+
+The [Clover iOS app](https://github.com/neonforestmist/Clover-Image-Tiny-iOS) provides a native masking workflow.
+Core ML resources are published [separately](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint-CoreML).
+
+Published Clover attention-only LoRAs are mechanically compatible in Diffusers,
+but they were trained for text-to-image, so evaluate each style's editing quality.
+The shipping iOS inpainting screen does not enable dynamic styles.
+[Read the adapter and deployment details](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint/blob/main/docs/MODEL_DETAILS.md#core-ml-and-style-mixing).
+
+## Limits and license
+
+Small text, hands, faces, exact logos, and very small masks can be difficult.
+Review generated edits before sharing. The model inherits the limitations and
+**CreativeML Open RAIL-M** obligations of Clover and Stable Diffusion 1.5 inpainting.
+
+[**Technical reference, evaluation, provenance, and citation →**](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint/blob/main/docs/MODEL_DETAILS.md)
 
-Designed and developed independently by Lukas Lozada Perez. Open weights under
-the CreativeML Open RAIL-M license; complete local inference is supported.
+Created by **Lukas Lozada Perez**.

docs/MODEL_DETAILS.md

@@ -0,0 +1,78 @@
+# Clover Inpaint HQ — technical reference
+
+[Back to the model card](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint).
+
+## Quality gate
+
+The release was evaluated on 24 deterministic, held-out, human-rated
+InpaintCOCO edits. Every output was also reviewed in three visual contact
+sheets before release.
+
+| Metric | Previous Clover inpaint | HQ release | SD 1.5 inpaint teacher |
+|---|---:|---:|---:|
+| Masked prompt CLIP similarity (higher) | 0.2642 | **0.2768** | 0.2820 |
+| Masked target MAE (lower) | 0.2510 | **0.2231** | 0.2156 |
+| Changed pixels outside the mask | 0 | **0** | 0 |
+
+The HQ release improves prompt alignment by 4.8% and reduces masked target
+error by 11.1% relative to the previous Clover inpainting release. The visual
+gate showed recognizable buses, dogs, trains, furniture, signs, and
+scene-consistent lighting where the compact candidates often collapsed into
+amorphous fills.
+
+## Selection provenance
+
+The release process compared the existing checkpoint, a 30,000-step full-U-Net
+distillation run, two fused context-LoRA refinements, partial weight blends,
+the full Stable Diffusion inpainting reference, and this Clover-component
+hybrid. The 30,000-step and context-LoRA candidates were rejected because they
+did not beat the existing release across both visual and quantitative gates.
+The published HQ architecture was the only Clover-compatible candidate that
+materially improved both prompt alignment and reconstruction.
+
+- Inpainting U-Net revision:
+  `stable-diffusion-v1-5/stable-diffusion-inpainting@8a4288a76071f7280aedbdb3253bdb9e9d5d84bb`
+- Clover components: `neonforestmist/Clover-Image-Tiny`
+- Evaluation dataset: `phiyodr/InpaintCOCO@1ffac84be2dfc5ad9afccad868522fad64457435`
+- Selection platform: Modal H100
+- Evaluation seed: `20260813`
+
+## Core ML and style mixing
+
+The companion iOS resources are published at
+[`neonforestmist/Clover-Image-Tiny-Inpaint-CoreML`](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint-CoreML).
+
+In Diffusers, the published Clover style LoRAs are mechanically compatible
+with this nine-channel U-Net because they modify attention projections only;
+those tensor shapes are unchanged from the four-channel model. They were
+trained for text-to-image, however, so masked-edit quality should be evaluated
+per style. LoRAs that modify the four-channel input convolution are not
+compatible.
+
+Dynamic Core ML loading is a separate deployment capability. The shipping iOS
+inpainting screen currently selects a stateless or chunked U-Net and does not
+enable styles. An adapter-aware stateful nine-channel export can provide up to
+three independently weighted slots, but it must include the matching adapter
+schema and be validated on its target devices. For a stateless deployment,
+fuse a compatible LoRA before conversion.
+
+## Limitations
+
+Small text, hands, faces, exact logos, and masks below latent resolution can
+still fail. Output quality depends on the source, mask, prompt, scheduler,
+guidance, seed, and step count. This release inherits the limitations and
+license obligations of Clover Image Tiny and Stable Diffusion 1.5 inpainting.
+
+## Citation
+
+```bibtex
+@software{lozadaperez2026cloverimagetinyinpaint,
+  author = {Lukas Lozada Perez},
+  title = {Clover Image Tiny Inpaint HQ: Local Context-Aware Image Inpainting},
+  year = {2026},
+  url = {https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint}
+}
+```
+
+Designed and developed independently by Lukas Lozada Perez. Open weights under
+the CreativeML Open RAIL-M license; complete local inference is supported.