Update README.md

README.md

@@ -3,6 +3,7 @@ license: creativeml-openrail-m
 tags:
 - stable-diffusion
 - stable-diffusion-1-5
+- realistic-vision
 - euler
 - axera
 - ax-m1
@@ -10,49 +11,120 @@ tags:
 - axmodel
 ---
 
-# AX-M1 (AX8850) — Stable Diffusion 1.5 **Euler 512** (AXMODEL weights)
+# AX-M1 (AX8850) — Realistic Vision (SD 1.5) **Euler 512** (AXMODEL weights)
 
-This repository hosts the compiled **`.axmodel`** weights for running **Stable Diffusion 1.5 (Euler / EulerDiscreteScheduler)** at **512×512** on **Radxa AI Core AX-M1 (AX8850)**.
+This repository hosts the compiled **`.axmodel`** weights for running **Realistic Vision (Stable Diffusion 1.5–based)** with **Euler / EulerDiscreteScheduler** at **512×512** on **Radxa AI Core AX-M1 (AX8850)**.
 
 **Runtime / scripts (GitHub):** https://github.com/Mojo24x7/SD1.5_AXM1-AX8850_Euler
 
-## Contents
+> These files are **compiled AXERA artifacts** (`.axmodel`) intended for AX-M1 / AX8850 inference via AXCLRT/axengine. They are not raw PyTorch weights.
+
+---
+
+## What’s inside
 
 Main weights:
-- `sd15_text_encoder_sim.axmodel` — CLIP text encoder (prompt → embeddings)
+- `sd15_text_encoder_sim.axmodel` — CLIP text encoder (prompt → text embeddings)
 - `unet.axmodel` — UNet denoiser (latent diffusion core)
 - `vae_decoder.axmodel` — VAE decoder (latent → RGB image)
 
-Optional (for img2img / masked workflows):
+Optional (needed for img2img / masked workflows):
 - `vae_encoder.axmodel` — VAE encoder (RGB → latent)
 
-## Expected shapes (Euler 512)
+---
+
+## Download
+
+### Option A — Git LFS (recommended)
+```bash
+git lfs install
+git clone https://huggingface.co/Mojo24x7/sd15-axm1-euler512-axmodels
+```
+
+### Option B — Hugging Face CLI
+```bash
+pip install -U "huggingface_hub[cli]"
+huggingface-cli download Mojo24x7/sd15-axm1-euler512-axmodels \
+  --local-dir sd15-axm1-euler512-axmodels
+```
+
+---
+
+## Where to place the files
+
+In the runtime repo, place these into:
+
+```text
+./axmodels/
+  sd15_text_encoder_sim.axmodel
+  unet.axmodel
+  vae_decoder.axmodel
+  vae_encoder.axmodel   (optional)
+```
+
+The runtime/scripts repo also expects supporting assets (tokenizer, scheduler config, VAE config). See the GitHub repo for the full folder layout.
+
+---
+
+## Expected model I/O (Euler 512)
+
+### Text encoder
+- input: `input_ids` `[1,77]` `int32`
+- output: `last_hidden_state` `[1,77,768]` `fp32`
+
+### UNet
+- inputs:
+  - `sample` `[1,4,64,64]` `fp32`  *(512/8 = 64 latent resolution)*
+  - `timestep` `[1]` `int32`
+  - `encoder_hidden_states` `[1,77,768]` `fp32`
+- output: `[1,4,64,64]` `fp32`
+
+### VAE decoder
+- input: `latent` `[1,4,64,64]` `fp32`
+- output: `[1,3,512,512]` `fp32` *(commonly in `[-1..1]` before postprocess)*
 
-- **Text encoder**
-  - input: `input_ids` `[1,77]` `int32`
-  - output: `last_hidden_state` `[1,77,768]` `fp32`
+### VAE encoder (optional)
+- input: image `[1,3,512,512]` `fp32`
+- output: latent `[1,4,64,64]` `fp32`
 
-- **UNet**
-  - inputs:
-    - `sample` `[1,4,64,64]` `fp32`  (512/8 = 64)
-    - `timestep` `[1]` `int32`
-    - `encoder_hidden_states` `[1,77,768]` `fp32`
-  - output: `[1,4,64,64]` `fp32`
+---
+
+## Runtime notes (important)
 
-- **VAE decoder**
-  - input: `latent` `[1,4,64,64]` `fp32`
-  - output: `[1,3,512,512]` `fp32` (typically in `[-1..1]` before postprocess)
+- The runtime scripts use **EulerDiscreteScheduler**.
+- Ensure `input_ids` and `timestep` are **int32** (int64 will fail in many AX pipelines).
+- Typical flow:
+  1) tokenize → text encoder
+  2) scheduler loop → UNet
+  3) VAE decode → image postprocess
+
+---
 
-## How to use
+## Base model: Realistic Vision
 
-These weights are intended to be used with the GitHub runtime scripts linked above, which:
-- run **EulerDiscreteScheduler**
-- ensure `input_ids` and `timestep` are **int32**
-- run text_encoder → UNet → VAE decode
+These compiled weights are derived from **Realistic Vision**, which is **Stable Diffusion 1.5–based**.
 
-Place the `.axmodel` files into your runtime folder under `./axmodels/`.
+When you reuse or redistribute these artifacts:
+- Follow the **CreativeML OpenRAIL-M** license terms.
+- Also follow **Realistic Vision** upstream terms (model card/license) where applicable.
+
+> Tip: If you want maximum clarity, add the exact Realistic Vision version you used (e.g., “Realistic Vision vX.X”) and link to its model card.
+
+---
+
+## Troubleshooting
+
+- If cloning is slow or files look tiny: you likely don’t have LFS installed.
+  - Run `git lfs install` and re-clone.
+- If the runtime says a model input type is wrong:
+  - Verify `timestep` is `int32`
+  - Verify `input_ids` is `int32`
+- If outputs look washed out:
+  - Check VAE postprocess and scaling (model outputs typically need `(x * 0.5 + 0.5)` then clamp to `[0..1]`).
+
+---
 
-## Notes
+## Credits
 
-- These are **compiled artifacts** for AX-M1 / AX8850 (not raw PyTorch weights).
-- Include the base model license and usage restrictions when redistributing.
+- **AX-M1 / AX8850** compilation and runtime packaging: Mojo24x7
+- Base architecture: Stable Diffusion 1.5 family (Realistic Vision derivative)