Update README.md

README.md

@@ -2,7 +2,32 @@
 license: creativeml-openrail-m
 ---
 
-## <a name="converting-models-to-coreml"></a> Converting Models to Core ML
+# Guernika
+
+This repository contains Guernika compatible models and instructions to convert existing models.
+
+## <a name="converting-models-to-guernika"></a> Converting Models to Guernika
+
+### <a name="converting-models-advanced"></a> Easy mode
+
+**Step 1:** Download and install [`Guernika Model Converter`](https://huggingface.co/Guernika/CoreMLStableDiffusion/resolve/main/GuernikaModelConverter.pkg).
+
+**Step 2:** Launch `Guernika Model Converter` from your `Applications` folder, this app may take a few seconds to load.
+
+**Step 3:** Once the app has loaded you will be able to select what model you want to convert:
+
+  - You can input the model identifier (e.g. CompVis/stable-diffusion-v1-4) to download from Hugging Face. You may have to log in to or register for your [Hugging Face account](https://huggingface.co), generate a [User Access Token](https://huggingface.co/settings/tokens) and use this token to set up Hugging Face API access by running `huggingface-cli login` in a Terminal window.
+    
+  - You can select a local model from your machine: `Select local model`
+
+  - You can select a local .CKPT model from your machine: `Select CKPT`
+
+**Step 4:** Once you've chosen the model you want to convert you can choose what modules to convert and/or if you want to chunk the UNet module (recommended for iOS/iPadOS devices).
+
+**Step 5:** Once you're happy with your selection click `Convert to Guernika` and wait for the app to complete conversion.
+**WARNING:** This command may download several GB worth of PyTorch checkpoints from Hugging Face and may take a long time to complete (15-20 minutes on an M1 machine).
+
+### <a name="converting-models-advanced"></a> Advance mode
 
 **Step 1:** Create a Python environment and install dependencies:
 
@@ -13,27 +38,43 @@ cd /path/to/unziped/scripts/location
 pip install -e .
 ```
 
-**Step 2:** Log in to or register for your [Hugging Face account](https://huggingface.co), generate a [User Access Token](https://huggingface.co/settings/tokens) and use this token to set up Hugging Face API access by running `huggingface-cli login` in a Terminal window.
+**Step 2:** Choose what model you want to convert:
 
-**Step 3a:** Navigate to the version of Stable Diffusion that you would like to use on [Hugging Face Hub](https://huggingface.co/models?search=stable-diffusion) and accept its Terms of Use. The default model version is [CompVis/stable-diffusion-v1-4](https://huggingface.co/CompVis/stable-diffusion-v1-4). The model version may be changed by the user as described in the next step.
+  **Huggin Face model:** Log in to or register for your [Hugging Face account](https://huggingface.co), generate a [User Access Token](https://huggingface.co/settings/tokens) and use this token to set up Hugging Face API access by running `huggingface-cli login` in a Terminal window.
+  Once you know what model you want to convert and have accepted its Terms of Use, run the following command replacing `<model-identifier>` with the desired model's identifier:
 
-**Step 3b:** You may also convert an existing model from a ckpt package by using the `convert_original_stable_diffusion_to_diffusers.py` script. After converting it you can continue using the `--model-location` argument to indicate the location of your converted model.
+```shell
+python -m python_coreml_stable_diffusion.torch2coreml --model-version <model-identifier> -o <output-directory> --convert-unet --convert-text-encoder --convert-vae-encoder --convert-vae-decoder --convert-safety-checker --bundle-resources-for-guernika --clean-up-mlpackages
+```
+
+  **Local model:** Run the following command replacing `<model-location>` with the desired model's location path:
+
+```shell
+python -m python_coreml_stable_diffusion.torch2coreml --model-location <model-location> -o <output-directory> --convert-unet --convert-text-encoder --convert-vae-encoder --convert-vae-decoder --convert-safety-checker --bundle-resources-for-guernika --clean-up-mlpackages
+```
 
-**Step 4:** Execute the following command from the Terminal to generate Core ML model files (`.mlpackage`) and Guernika compatible model.
+  **Local CKPT:** Run the following command replacing `<checkpoint-path>` with the desired CKPT's location path:
 
 ```shell
-python -m python_coreml_stable_diffusion.torch2coreml --convert-unet --convert-text-encoder --convert-vae-encoder --convert-vae-decoder --convert-safety-checker -o <output-mlpackages-directory> --bundle-resources-for-swift-cli
+python -m python_coreml_stable_diffusion.torch2coreml --checkpoint-path <checkpoint-path> -o <output-directory> --convert-unet --convert-text-encoder --convert-vae-encoder --convert-vae-decoder --convert-safety-checker --bundle-resources-for-guernika --clean-up-mlpackages
 ```
 
-**WARNING:** This command may download several GB worth of PyTorch checkpoints from Hugging Face.
+**WARNING:** These commands may download several GB worth of PyTorch checkpoints from Hugging Face.
+
+This generally takes 15-20 minutes on an M1 MacBook Pro. Upon successful execution, the neural network models that comprise Stable Diffusion's model will have been converted from PyTorch to Guernika and saved into the specified `<output-directory>`.
+
 
-This generally takes 15-20 minutes on an M1 MacBook Pro. Upon successful execution, the 4 neural network models that comprise Stable Diffusion will have been converted from PyTorch to Core ML (`.mlpackage`) and saved into the specified `<output-mlpackages-directory>`. Some additional notable arguments:
+#### <a name="converting-models--arguments"></a> Notable arguments
 
 - `--model-version`: The model version defaults to [CompVis/stable-diffusion-v1-4](https://huggingface.co/CompVis/stable-diffusion-v1-4). Developers may specify other versions that are available on [Hugging Face Hub](https://huggingface.co/models?search=stable-diffusion), e.g. [stabilityai/stable-diffusion-2-base](https://huggingface.co/stabilityai/stable-diffusion-2-base) & [runwayml/stable-diffusion-v1-5](https://huggingface.co/runwayml/stable-diffusion-v1-5).
-- 
+
 - `--model-location`: The location of a local model defaults to `None`.
+  
+- `--checkpoint-path`: The location of a local .CKPT model defaults to `None`.
+
+- `--bundle-resources-for-guernika`: Compiles all 4 models and bundles them along with necessary resources for text tokenization into `<output-mlpackages-directory>/Resources` which should provided as input to the Swift package. This flag is not necessary for the diffusers-based Python pipeline.
 
-- `--bundle-resources-for-swift-cli`: Compiles all 4 models and bundles them along with necessary resources for text tokenization into `<output-mlpackages-directory>/Resources` which should provided as input to the Swift package. This flag is not necessary for the diffusers-based Python pipeline.
+- `--clean-up-mlpackages`: Cleans up created .mlpackages leaving only the compiled model.
 
 - `--chunk-unet`: Splits the Unet model in two approximately equal chunks (each with less than 1GB of weights) for mobile-friendly deployment. This is **required** for ANE deployment on iOS and iPadOS. This is not required for macOS. Swift CLI is able to consume both the chunked and regular versions of the Unet model but prioritizes the former. Note that chunked unet is not compatible with the Python pipeline because Python pipeline is intended for macOS only. Chunking is for on-device deployment with Swift only.