Create README.md

README.md

@@ -0,0 +1,187 @@
+---
+license: creativeml-openrail-m
+base_model: s6yx/ReV_Animated
+tags:
+  - mnn
+  - stable-diffusion
+  - stable-diffusion-1.5
+  - text-to-image
+  - anime
+  - on-device
+  - quantized
+  - android
+---
+
+# ReV Animated (MNN)
+
+This repository provides an MNN-format conversion of
+[s6yx/ReV_Animated](https://huggingface.co/s6yx/ReV_Animated) (v1.2.2, fp16)
+for use with the [nezumi-ai](https://github.com/mouse0329/nezumi-ai) image generation engine —
+a fully offline AI chat app for Android supporting on-device image generation.
+
+A Windows CLI (`nezumi-ai-sd-cli`) is also provided for testing/debugging on desktop, but the
+primary target platform is Android. This model is not bundled with the app — users download it
+separately and individually agree to its license terms.
+
+> **Platform note**: `nezumi-ai-sd-cli` currently builds for **Windows only** (`.exe`).
+> A Linux build is planned.
+
+## Variants
+
+SD1.5 models are distributed in a single quantization variant (unlike the SDXL/Illustrious
+line, which offers int4/int8 variants):
+
+| File | UNet quantization | Size |
+|---|---|---|
+| `ReV_Animated-mnn-int8-block32.zip` | 8-bit, block size 32 | ~1.23 GB |
+
+## Model Provenance
+
+| Field | Value |
+|---|---|
+| Base model | [s6yx/ReV_Animated](https://huggingface.co/s6yx/ReV_Animated), `rev_1.2.2-fp16.safetensors` |
+| Original source | Checkpoint merge by s6yx; handles anime, semi-realistic, and fantasy styles in one model |
+| Format | MNN (`clip_v2.mnn` + `.weight`, `unet.mnn` + `.weight`, `vae_decoder_fp16.mnn` + `.weight`, `token_emb.bin`, `pos_emb.bin`, `tokenizer.json`) |
+| Conversion tool | [`convert_hf_to_mnn_sd.py`](https://github.com/mouse0329/nezumi-ai/blob/main/mnn-sd-engine/conversion/convert_hf_to_mnn_sd.py) (nezumi-ai) |
+
+### Conversion steps
+
+Unlike other conversions in this collection, the upstream model is distributed as a single
+`.safetensors` checkpoint rather than a diffusers-format repository, so an extra pre-conversion
+step is required before the MNN conversion script can read it.
+
+```bash
+# 1. Download the fp16 checkpoint
+huggingface-cli download s6yx/ReV_Animated rev_1.2.2/rev_1.2.2-fp16.safetensors --local-dir .
+
+# 2. Convert single-file safetensors -> diffusers format
+python -c "
+from diffusers import StableDiffusionPipeline
+import torch
+
+pipe = StableDiffusionPipeline.from_single_file(
+    './rev_1.2.2/rev_1.2.2-fp16.safetensors',
+    torch_dtype=torch.float16,
+    safety_checker=None,
+)
+pipe.save_pretrained('./ReV_Animated_diffusers')
+"
+
+# 3. Convert diffusers format -> MNN
+python convert_hf_to_mnn_sd.py \
+    --model ./ReV_Animated_diffusers \
+    --out ./out/ReV_Animated \
+    --size 512 \
+    --unet-bits 8 \
+    --unet-block 32 \
+    --clip-bits 8 \
+    --vae-bits 8
+```
+
+No fine-tuning or retraining was performed — weights are unchanged from the original
+checkpoint aside from the diffusers-format repack and the MNN format conversion/quantization
+above.
+
+### Output files
+
+```
+clip_v2.mnn                0.13 MB
+clip_v2.mnn.weight       148.92 MB
+model.json                 0.00 MB
+pos_emb.bin                 0.23 MB
+token_emb.bin              72.38 MB
+tokenizer.json               2.12 MB
+unet.mnn                    1.13 MB
+unet.mnn.weight          911.38 MB
+vae_decoder_fp16.mnn        0.22 MB
+vae_decoder_fp16.mnn.weight 94.38 MB
+TOTAL                    1230.89 MB
+```
+
+## License
+
+- **Original model license**: CreativeML Open RAIL-M ([full text](https://huggingface.co/spaces/CompVis/stable-diffusion-license))
+  — all credit for the weights and merge work goes to s6yx.
+- **Redistribution**: Permitted under the original model's license.
+- **Commercial use**: Permitted within the terms of the RAIL-M license.
+- **Attribution**: Required (see above).
+
+Please read and comply with the original license before using this model.
+
+This checkpoint inherits the original model's use-based restrictions in full
+(see Attachment A of the [full license text](https://huggingface.co/spaces/CompVis/stable-diffusion-license)),
+including prohibitions on use for exploiting minors, generating disinformation, harassment,
+discrimination, unauthorized medical advice, and law-enforcement/immigration profiling.
+
+> Note: this is a checkpoint merge, meaning it is derived from multiple upstream Stable
+> Diffusion models. The RAIL-M license and its use-based restrictions apply to the merged
+> result as distributed by s6yx.
+
+> Note: the conversion script itself is part of the nezumi-ai project and licensed separately
+> under LGPL v3 / a commercial license (see [LICENSE.md](https://github.com/mouse0329/nezumi-ai/blob/main/LICENSE.md)).
+> That license applies to the *code*, not to this model checkpoint.
+
+## Requirements (Android)
+
+| Item | Minimum | Recommended |
+|---|---|---|
+| Android Version | 12 (API 31) | 14+ (API 34+) |
+| RAM | 4GB | 6GB+ |
+| Storage | 3GB free | 5GB+ |
+| GPU | Optional — OpenCL-capable GPU (Adreno, Mali, PowerVR) | Recommended |
+
+> SD1.5 requirements are lower than SDXL/Illustrious (8GB RAM minimum) — see that model's README
+> for comparison.
+
+## Usage
+
+### Android (primary)
+
+Used automatically by the [nezumi-ai](https://github.com/mouse0329/nezumi-ai) app's image-generation
+feature (MNN backend, GPU/OpenCL → CPU fallback). Download/select this model from within the app;
+manual extraction is not required on Android.
+
+### Windows CLI (testing/debugging)
+
+Distributed as a zip archive. Extract it before use — in PowerShell:
+
+```powershell
+Expand-Archive ReV_Animated-mnn-int8-block32.zip C:\sd-model
+```
+
+Then run:
+
+```bat
+nezumi-ai-sd-cli "C:\sd-model" "1girl, fantasy knight, detailed armor, anime style" --steps 20 --width 512 --height 768 --backend cpu --out out.png
+```
+
+#### Options
+
+| Option | Description | Default |
+|---|---|---|
+| `<model_path>` | Path to the extracted MNN model folder | — |
+| `<prompt>` | Text prompt | — |
+| `--negative <text>` | Negative prompt | empty |
+| `--width <n>` / `--height <n>` | Image size | 512 / 512 |
+| `--steps <n>` | Sampling steps | 20 |
+| `--cfg <f>` | CFG scale | 7.0 |
+| `--seed <n>` | Seed (negative = random) | -1 |
+| `--scheduler <name>` | Sampling scheduler: `euler`\|`ddim`\|`dpm`\|`dpm++2m`\|`dpm++2m-karras`\|`lcm`\|`eulera`\|`unipc` | `dpm++2m` |
+| `--backend <name>` | `cpu`\|`opencl` | `cpu` |
+| `--out <path>` | Output path. `.ppm` always works; `.png` requires `stb_image_write.h` | — |
+
+> Prompt order matters for this model — words near the front of the prompt carry more weight.
+> A common structure is: content type → description → style → composition. Works well across
+> anime, semi-realistic, and fantasy-landscape prompts.
+
+## Roadmap
+
+- [ ] Linux build of `nezumi-ai-sd-cli`
+- [ ] macOS build
+- [ ] SDXL support
+- [ ] Additional quantization variants
+
+## Disclaimer
+
+This is an unofficial, community conversion and is not affiliated with or endorsed
+by s6yx.