Model card redesign: banner, gallery widget, showcase images

.gitattributes

@@ -38,3 +38,18 @@ figures/fig3_unseen_artist_oc.jpg filter=lfs diff=lfs merge=lfs -text
 figures/fig4_ref_guidance.jpg filter=lfs diff=lfs merge=lfs -text
 figures/fig5_corrections.jpg filter=lfs diff=lfs merge=lfs -text
 figures/fig6_failures.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/banner.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/girl_beach.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/girl_cake.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/girl_classroom.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/girl_neon.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/girl_sakura.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/girl_umbrella.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/man_beach.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/man_cafe.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/man_library.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/man_night_rain.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/man_sakura.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/man_snow.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/ref_girl.jpg filter=lfs diff=lfs merge=lfs -text
+showcase/ref_man.jpg filter=lfs diff=lfs merge=lfs -text

README.md

@@ -13,75 +13,145 @@ tags:
 - character-consistency
 - style-transfer
 - anime
+widget:
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1boy, solo, full body, walking, hands in pockets, city, street, night, rain"
+  output:
+    url: showcase/man_night_rain.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1boy, solo, upper body, sitting, holding cup, drinking, cafe, indoors, window, sunlight"
+  output:
+    url: showcase/man_cafe.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1boy, solo, cowboy shot, looking at viewer, smile, beach, ocean, sunset"
+  output:
+    url: showcase/man_beach.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1boy, solo, portrait, from side, looking afar, cherry blossoms, petals"
+  output:
+    url: showcase/man_sakura.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1boy, solo, upper body, reading, holding book, library, bookshelf"
+  output:
+    url: showcase/man_library.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1boy, solo, full body, standing, snow, forest, winter"
+  output:
+    url: showcase/man_snow.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1girl, solo, full body, walking, smile, city, street, night, neon lights"
+  output:
+    url: showcase/girl_neon.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1girl, solo, upper body, sitting, eating, cake, cafe, indoors"
+  output:
+    url: showcase/girl_cake.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1girl, solo, cowboy shot, looking back, smile, beach, ocean, sunset"
+  output:
+    url: showcase/girl_beach.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1girl, solo, portrait, closed eyes, smile, cherry blossoms, petals, wind"
+  output:
+    url: showcase/girl_sakura.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1girl, solo, full body, sitting, on chair, crossed legs, classroom, sunlight"
+  output:
+    url: showcase/girl_classroom.jpg
+- text: "masterpiece, best quality, score_7, newest, highres, absurdres, safe, 1girl, solo, upper body, holding umbrella, rain, street, looking at viewer"
+  output:
+    url: showcase/girl_umbrella.jpg
 ---
 
+<div align="center">
+
+<img src="showcase/banner.jpg" width="100%" alt="Anima Reference Adapter">
+
 # Anima Reference Adapter (pilot, r32)
 
-A LoRA + inference recipe that lets [Anima](https://huggingface.co/circlestone-labs/Anima) take a
-**character and its drawing style from one reference image**, while **pose, framing and background
-follow the prompt**. The prompt does not need the character's name, artist tags or appearance tags.
+**Character and style from one image. Pose, place and framing from your prompt.**
 
-> **Attribution notice.** The CircleStone Model is licensed by CircleStone Labs LLC under the
-> CircleStone Non-Commercial License. Copyright CircleStone Labs LLC. IN NO EVENT SHALL CIRCLESTONE LABS
-> LLC BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
-> OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH USE OF THIS MODEL.
-> **These weights are a modified derivative of the CircleStone Model (Anima base v1.0).** This is an
-> independent project, not an official product of CircleStone Labs and not endorsed by it. See
-> [NOTICE.txt](NOTICE.txt) and [LICENSE.md](LICENSE.md). Non-commercial use only.
+[![Weights](https://img.shields.io/badge/%F0%9F%A4%97%20weights-anima--ref--adapter-ffcc4d)](https://huggingface.co/ElectronGirl/anima-ref-adapter)
+[![Code](https://img.shields.io/badge/%F0%9F%A7%A9%20ComfyUI-nodes-1f6feb)](https://github.com/ElectronGirl/ComfyUI-Anima-Ref-Adapter)
+[![Report](https://img.shields.io/badge/%F0%9F%93%84%20report-method%20%26%20results-8a63d2)](https://github.com/ElectronGirl/ComfyUI-Anima-Ref-Adapter/blob/main/docs/report.md)
+[![Code license](https://img.shields.io/badge/code-Apache--2.0-2ea44f)](https://github.com/ElectronGirl/ComfyUI-Anima-Ref-Adapter/blob/main/LICENSE)
+[![Weights license](https://img.shields.io/badge/weights-CircleStone%20Non--Commercial-555)](https://huggingface.co/ElectronGirl/anima-ref-adapter/blob/main/LICENSE.md)
 
-![held-out characters](figures/fig2_heldout.jpg)
+</div>
 
-*Reference · adapter with a scene-only prompt · same prompt without adapter · image generated with full
-character tags. These characters were held out of training.*
+A LoRA + ComfyUI recipe for [Anima](https://huggingface.co/circlestone-labs/Anima): give one reference
+image and a prompt that only describes the scene. Hair, eyes, outfit and accessories come from the image;
+pose, background and composition follow the prompt. No character name, artist or appearance tags needed.
 
-## Use it (ComfyUI)
+> **This is not a plain LoRA.** The reference must be attached as an extra latent frame with shifted RoPE.
+> Use the nodes and workflows from **[ElectronGirl/ComfyUI-Anima-Ref-Adapter](https://github.com/ElectronGirl/ComfyUI-Anima-Ref-Adapter)**.
 
-This is **not a plain LoRA**: the reference must be attached as an extra latent frame with shifted RoPE.
-Use the nodes and workflows from **[ElectronGirl/ComfyUI-Anima-Ref-Adapter](https://github.com/ElectronGirl/ComfyUI-Anima-Ref-Adapter)**:
+## Gallery
 
-1. Put `anima_ref_adapter_pilot_r32.safetensors` in `ComfyUI/models/loras/`.
-2. Install the node pack into `ComfyUI/custom_nodes/` and restart.
-3. Open `workflows/anima_ref_adapter.json` (or `_pag.json`), load a reference image, write a
-   scene-only prompt (quality tags, gender, `solo`, framing, pose, expression, background).
+Prompt: `masterpiece, best quality, score_7, newest, highres, absurdres, safe, <gender>, solo, <scene>`. Euler 28 steps, cfg 4.5, reference guidance 4.5 + APG.
+Not cherry-picked.
+
+<table>
+<tr><td rowspan="2" align="center" valign="middle" width="25%"><img src="showcase/ref_man.jpg" width="100%"><br><b>Reference A</b><br><sub>input image</sub></td><td align="center" valign="top" width="25%"><img src="showcase/man_night_rain.jpg" width="100%"><br><sub><code>full body, walking, hands in pockets, city, street, night, rain</code></sub></td><td align="center" valign="top" width="25%"><img src="showcase/man_cafe.jpg" width="100%"><br><sub><code>upper body, sitting, holding cup, drinking, cafe, indoors, window, sunlight</code></sub></td><td align="center" valign="top" width="25%"><img src="showcase/man_beach.jpg" width="100%"><br><sub><code>cowboy shot, looking at viewer, smile, beach, ocean, sunset</code></sub></td></tr>
+<tr><td align="center" valign="top" width="25%"><img src="showcase/man_sakura.jpg" width="100%"><br><sub><code>portrait, from side, looking afar, cherry blossoms, petals</code></sub></td><td align="center" valign="top" width="25%"><img src="showcase/man_library.jpg" width="100%"><br><sub><code>upper body, reading, holding book, library, bookshelf</code></sub></td><td align="center" valign="top" width="25%"><img src="showcase/man_snow.jpg" width="100%"><br><sub><code>full body, standing, snow, forest, winter</code></sub></td></tr>
+</table>
+
+<table>
+<tr><td rowspan="2" align="center" valign="middle" width="25%"><img src="showcase/ref_girl.jpg" width="100%"><br><b>Reference B</b><br><sub>input image</sub></td><td align="center" valign="top" width="25%"><img src="showcase/girl_neon.jpg" width="100%"><br><sub><code>full body, walking, smile, city, street, night, neon lights</code></sub></td><td align="center" valign="top" width="25%"><img src="showcase/girl_cake.jpg" width="100%"><br><sub><code>upper body, sitting, eating, cake, cafe, indoors</code></sub></td><td align="center" valign="top" width="25%"><img src="showcase/girl_beach.jpg" width="100%"><br><sub><code>cowboy shot, looking back, smile, beach, ocean, sunset</code></sub></td></tr>
+<tr><td align="center" valign="top" width="25%"><img src="showcase/girl_sakura.jpg" width="100%"><br><sub><code>portrait, closed eyes, smile, cherry blossoms, petals, wind</code></sub></td><td align="center" valign="top" width="25%"><img src="showcase/girl_classroom.jpg" width="100%"><br><sub><code>full body, sitting, on chair, crossed legs, classroom, sunlight</code></sub></td><td align="center" valign="top" width="25%"><img src="showcase/girl_umbrella.jpg" width="100%"><br><sub><code>upper body, holding umbrella, rain, street, looking at viewer</code></sub></td></tr>
+</table>
 
-Recommended: Anima base v1.0 without the turbo LoRA, bf16 compute, Euler 30 steps, `cfg` 4.5,
-`ref_guidance` 4.5–6 with `apg` correction.
+### Held-out characters
 
-## Method in one paragraph
+<img src="figures/fig2_heldout.jpg" width="100%">
 
-The reference image is letterboxed to the output size, VAE-encoded and appended as a second frame on
-the DiT's time axis. It gets timestep 0 (clean) and its RoPE h coordinates are shifted by one target
-height, so the video prior cannot copy it pixel-aligned (no pose copying, unlike an aligned temporal
-reference). A rank-32 LoRA (45.9M parameters, all attention and MLP projections of the 28 blocks)
-learns to read the frame; it is applied only to model calls that carry the reference. Guidance
-separates text and reference scales, with adaptive projected guidance against over-saturation.
-Full details, data and failure modes: [report.md](report.md).
+<sub>reference · adapter with a scene-only prompt · same prompt without the adapter · image generated with the full character tags</sub>
 
-## Training
+## Quick start (ComfyUI)
 
-| | |
+1. Put `anima_ref_adapter_pilot_r32.safetensors` in `ComfyUI/models/loras/`.
+2. `git clone https://github.com/ElectronGirl/ComfyUI-Anima-Ref-Adapter` into `ComfyUI/custom_nodes/`, restart.
+3. Open `workflows/anima_ref_adapter.json`, load a reference image, write a scene-only prompt.
+
+| | recommended | notes |
+|---|---|---|
+| base model | Anima base v1.0 | no turbo LoRA (the adapter was trained on the base model) |
+| compute | bf16 (`ModelComputeDtype`) | Anima overflows in fp16 |
+| sampler | Euler, 28-30 steps, `simple` | single-resolution samplers; SamplerSPEED's half-resolution stage is unreliable |
+| `cfg` | 4.5 | text guidance |
+| `ref_guidance` | 4.5 - 6 | 1 = weak and cheaper; higher = more character detail and style, more saturation |
+| `correction` | `apg` | or `rescale` (phi 0.5) |
+| prompt | quality + gender + `solo` + scene tags | no character name, artist tag or appearance tags |
+
+## How it works
+
+The reference image is letterboxed to the output size, VAE-encoded and appended as a **second frame** on
+the DiT's time axis. It is fed **clean** (timestep 0) and its **RoPE h coordinates are shifted by one
+target height**, so the video prior cannot copy it pixel-aligned (no pose copying). A **rank-32 LoRA**
+(45.9M parameters, all attention and MLP projections of the 28 blocks), applied only to calls that carry
+the reference, learns to read it. Guidance separates text and reference scales, with adaptive projected
+guidance against over-saturation. Full details: [report.md](report.md).
+
+| training | |
 |---|---|
-| base | Anima base v1.0 (frozen), flow matching, shift 3 |
-| data | 3,600 images generated by Anima: 600 groups of one character in one artist style × 6 scenes; 300 characters, 427 artists; exact Danbooru appearance/outfit tags per character; 12 characters held out |
-| pairs | 17,280 (reference, target) pairs within a group; target prompt keeps scene tags only (70%), + some appearance tags (20%), or nothing (10%) |
-| optimization | 2,000 steps, batch 4, AdamW 1e-4 cosine, bf16, 2.4 h on one RTX PRO 6000 Max-Q |
+| data | 3,600 images generated by Anima: 600 groups of one character in one artist style x 6 scenes; 300 characters, 427 artists; 12 characters held out |
+| pairs | 17,280 (reference, target) pairs; target prompt keeps scene tags only (70%), + some appearance tags (20%), or nothing (10%) |
+| optimization | flow matching, 2,000 steps, batch 4, AdamW 1e-4 cosine, bf16; 2.4 h on one RTX PRO 6000 Max-Q |
 
 ## Limitations
 
-- Pilot scale. Identity transfer is much stronger than style transfer; painterly styles barely transfer.
-- Small patterns, scars, earrings and unusual skin tones are often lost; large garments may drift in color.
-- The character occasionally reappears as an object in the scene.
-- Samplers with a half-resolution stage (SamplerSPEED) are unreliable.
-- Inherits Anima's biases; trained only on synthetic images.
+- **Pilot release**: 300 training characters, 2,000 steps, rank 32.
+- Identity transfers much better than style; strongly painterly styles barely transfer.
+- Small patterns, scars, earrings and unusual skin tones are often lost; large garments can drift in color.
+- The reference character occasionally reappears as an object in the scene.
+- Trained only on images generated by Anima; it inherits the base model's biases.
+
+Artist names were used only as generation tags. Please respect artists: do not pass off imitations as
+their work, and follow the use restrictions in §4 of [LICENSE.md](LICENSE.md).
+
+## License and attribution
+
+**Non-commercial.** These weights are a modified derivative of the CircleStone Model (Anima base v1.0),
+distributed under the CircleStone Non-Commercial License ([LICENSE.md](LICENSE.md), [NOTICE.txt](NOTICE.txt)).
+This is an independent project, not an official product of CircleStone Labs and not endorsed by it.
 
-Artist names were used only as generation tags. Please respect artists: do not use this to pass off
-imitations as their work, and follow the license's restrictions on use (§4 of LICENSE.md).
+> The CircleStone Model is licensed by CircleStone Labs LLC under the CircleStone Non-Commercial License. Copyright CircleStone Labs LLC. IN NO EVENT SHALL CIRCLESTONE LABS LLC BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH USE OF THIS MODEL.
 
 ## Files
 
 | file | |
 |---|---|
-| `anima_ref_adapter_pilot_r32.safetensors` | LoRA (bf16, ComfyUI key format `diffusion_model.*.lora_down/lora_up/alpha`, 840 tensors) |
+| `anima_ref_adapter_pilot_r32.safetensors` | LoRA, bf16, ComfyUI key format (`diffusion_model.*.lora_down / lora_up / alpha`, 840 tensors) |
 | `report.md`, `figures/` | technical report |
 | `workflows/` | ComfyUI workflows |
+| `showcase/` | gallery images |
 | `LICENSE.md`, `NOTICE.txt` | CircleStone Non-Commercial License and attribution notice |