From 57c686fb00fe39c9766057af0198e12450533016 Mon Sep 17 00:00:00 2001 From: Aaron Liu Date: Thu, 1 Feb 2024 18:42:35 -0500 Subject: [PATCH] crudely import docs from wiki --- docs/Compatibility-List.md | 20 ++++++++++++++ docs/Guide.md | 42 ++++++++++++++++++++++++++++ docs/Home.md | 12 ++++++++ docs/How-to-ask-for-help.md | 22 +++++++++++++++ docs/Misc.md | 1 + docs/Model-Conversion-Guide.md | 36 ++++++++++++++++++++++++ docs/Troubleshooting.md | 40 +++++++++++++++++++++++++++ docs/favicon.svg | 50 +--------------------------------- 8 files changed, 174 insertions(+), 49 deletions(-) create mode 100644 docs/Compatibility-List.md create mode 100644 docs/Guide.md create mode 100644 docs/Home.md create mode 100644 docs/How-to-ask-for-help.md create mode 100644 docs/Misc.md create mode 100644 docs/Model-Conversion-Guide.md create mode 100644 docs/Troubleshooting.md diff --git a/docs/Compatibility-List.md b/docs/Compatibility-List.md new file mode 100644 index 0000000..5b1f612 --- /dev/null +++ b/docs/Compatibility-List.md @@ -0,0 +1,20 @@ +# Upscayl Compatibility + +### HELP US EXTEND THIS LIST BY SUBMITTING SUGGESTIONS IN THE [ISSUES TAB](https://github.com/upscayl/upscayl/issues)🙏🏻 + +## Operating System +- Ubuntu 20.04+ +- Windows 10+ +- macOS 12+ + - In the next release, we will add back macOS 11 support. + +## GPU + +Working integrated GPUs: +- Intel HD Graphics 620 (credit: [@Axe7bravo](https://github.com/upscayl/upscayl/issues/382)) +- Intel Iris Graphics (credit: [@arrhoegs](https://github.com/orgs/upscayl/discussions/571)) +- Most AMD Vega GPUs (credit: [@Yaki-0](https://github.com/upscayl/upscayl/issues/448) for Vega 8 Mobile, [@CloakTheLurker](https://github.com/upscayl/upscayl/issues/436) for Vega 10) + +All dedicated GPUs are assumed to work, except for the following that have been reported to be not working: +- GTX 7xx series +- GT 920M ? (see [comment](https://github.com/upscayl/upscayl/issues/401#issuecomment-1659604580)) \ No newline at end of file diff --git a/docs/Guide.md b/docs/Guide.md new file mode 100644 index 0000000..1f539ee --- /dev/null +++ b/docs/Guide.md @@ -0,0 +1,42 @@ +This is where you can find guides and tutorials for Upscayl. + +### HELP US EXTEND THIS LIST BY SUBMITTING SUGGESTIONS IN DA [ISSUES TAB](https://github.com/upscayl/upscayl/issues) 🙏🏻 + +## GPU ID +The GPU ID is used to manually specify a Vulkan enabled GPU to be used for upscaling images. According to the Real-ESRGAN documentation, you can use this option even for multi-GPUs. + +To find out the GPU ID, follow these steps: +1. Open Upscayl and (try to) upscayl an image. +2. Go to the Settings tab and scroll down till you see the logs area. +3. You can now see all the GPU IDs available to you. As you can see from the image, 1 is Nvidia, 2 is llvmpipe and 0 is AMD Radeon. +![image](https://github.com/upscayl/upscayl/assets/25067102/23aabc8d-9844-4366-b34b-e6eeb93385c7) + * This screenshot is only an example. Actual ID values may vary. +4. Now in the 'GPU ID' input box, you can enter: +`0` +`1` +`2` +or even `0,1,2` + * On Windows, this setting may be overridden by the system if Upscayl has not been [set to performance mode](https://youtube.com/watch?v=sxvs6qYHJmc) under advanced display settings. + * This doesn't distribute the load evenly due to Real-ESRGAN shenanigans. See [#465](upscayl/upscayl/issues/465) for details. + +## Logs +The logs appear in the Settings tab. + + +To copy a log, you can press the COPY button and to paste it in the GitHub issue template for bug reports. + +## Custom Models +Since Upscayl v2.5, you can load your own NCNN models into Upscayl. To convert models from PyTorch, see [🖥️ Model Conversion Guide](../%F0%9F%96%A5%EF%B8%8F-Model-Conversion-%E2%80%90-Create-more-AI-models!). You could also load Upscayl's official [Custom Models Repository](https://github.com/upscayl/custom-models). + +To use your custom models, follow these steps: +1. Make a folder called "models". +2. Put your NCNN models (in .bin + .param format) into the "models" folder. +3. Open Upscayl. +4. Go to the Settings tab and scroll down until you see the "Add Custom Models" area and the "Select Folder" button. +5. Select the "models" folder you created in step 1. +6. Go to the Upscayl tab and select the Upscayling type to the filename of the custom model you want to use. + +## Scale Option +Since v2.8, Upscayl emulates the scale option by Downscayling the x4 image for unsupported models. + +Not all models support x1, x2 and x3; all the default models only support x4. To use other scales as native model output, you can get the compatible models from the [Custom Models Repository](https://github.com/upscayl/custom-models). For example, with the `realesr-animevideov3-x2` model, you can use the scale x2; with `realesr-animevideov3-x3`, you can use the scale x3. \ No newline at end of file diff --git a/docs/Home.md b/docs/Home.md new file mode 100644 index 0000000..786c1f0 --- /dev/null +++ b/docs/Home.md @@ -0,0 +1,12 @@ +# Welcome to the Upscayl wiki! + +Here we're trying to build documentation around Upscayl for everyone. If you have any suggestions, please feel free to let us know! :) + +## Contents +- [🙋 How to ask for help?](https://github.com/upscayl/upscayl/wiki/%F0%9F%99%8B-How-to-ask-for-help%3F) +- [🧩 Compatibility List](https://github.com/upscayl/upscayl/wiki/Compatibility-List) +- [📖 User Guide](https://github.com/upscayl/upscayl/wiki/Guide) +- [🔨 Troubleshooting](https://github.com/upscayl/upscayl/wiki/Troubleshooting) +- [🖥️ Model Conversion Guide](https://github.com/upscayl/upscayl/wiki/Model-Conversion-Guide) +- [🤫 Miscellaneous Configuration](https://github.com/upscayl/upscayl/wiki/Misc) +- [🤯 Using Upscayl on Windows and Linux with only a CPU](https://github.com/upscayl/upscayl/issues/390) \ No newline at end of file diff --git a/docs/How-to-ask-for-help.md b/docs/How-to-ask-for-help.md new file mode 100644 index 0000000..d57eaf9 --- /dev/null +++ b/docs/How-to-ask-for-help.md @@ -0,0 +1,22 @@ +# How to Ask for Help on Upscayl's GitHub + +> [!NOTE] +**If you're having issues with the Mac App Store version of Upscayl, please email [Nayam Amarshe](mailto:nayam.emikx@aleeas.com).** + +> [!WARNING] +**Please do not Email or Telegram us for any bugs or issues that you encounter. You will not receive any replies. We only use GitHub issues for issue tracking.** + +GitHub is a powerful platform that fosters collaboration and open-source development. If you're new to GitHub and need assistance with Upscayl, follow these steps to effectively ask for help: + +### 1. Search for Similar Issues +Before posting a new issue, [search the repository's issue tracker](https://github.com/upscayl/upscayl/issues) to check if someone else has encountered a similar problem. Also [check the discussions tab](https://github.com/upscayl/upscayl/discussions) for any pre-existing discussions. This helps to avoid duplicate issues and ensures that you're not asking a question that has already been answered. You should also chech the [FAQ](https://github.com/upscayl/upscayl/tree/main#-faq). + +### 2. Provide Logs and Context +- To create a new issue, go to the [Issues tab](https://github.com/upscayl/upscayl/issues) and click **'New Issue'**. + +Make sure to provide detailed context about the problem you're facing. Include relevant information such as the logs, version of the software, the steps to reproduce the issue, and any error messages you've encountered. This will help others understand your problem better and provide more accurate assistance. + +If you don't know how to copy/see the logs, [follow this link](https://github.com/upscayl/upscayl/wiki/Guide#logs). + +### 3. Be Clear and Specific +Clearly articulate your issue or question in a concise manner. The title should clearly mention the problem. Avoid ambiguous language and provide specific details about what you're trying to achieve. This will make it easier for others to understand your problem and offer a targeted solution. Our default issue template provides a suggested, organized way to do this. \ No newline at end of file diff --git a/docs/Misc.md b/docs/Misc.md new file mode 100644 index 0000000..dffee6d --- /dev/null +++ b/docs/Misc.md @@ -0,0 +1 @@ +- [Using Upscayl on Windows without GPU](https://github.com/orgs/upscayl/discussions/580) \ No newline at end of file diff --git a/docs/Model-Conversion-Guide.md b/docs/Model-Conversion-Guide.md new file mode 100644 index 0000000..ced3bf5 --- /dev/null +++ b/docs/Model-Conversion-Guide.md @@ -0,0 +1,36 @@ +This guide explains how you can convert PyTorch models to NCNN models for Upscayl. + +> [!IMPORTANT] +> Only PyTorch models are guaranteed to work. You can use a similar process for ONNX models (use onnxsim to simplify the model, install ONNX in dependencies and replace the orange blocks with their cyan equivalents), but it can often fail. + +## Prerequisites +- [chaiNNer](https://github.com/chaiNNer-org/chaiNNer) + - [This .chn file](https://gist.github.com/aaronliu0130/38b996f360dfee86d71130f129920f3a/raw/f06e711e03a4a239e6dc041fadf890a26fdd979a/pth2bin.chn). Right click the link, click "Save link as" and save it wherever you want. +- A model in PyTorch (.pth) format. This guide is for converting PyTorch to NCNN (Upscayl's format) only. + - You can get models from . +- A Text Editor + +## Steps + +1. Open chaiNNer and inside its dependency manager (the download button in the top right corner) install PyTorch and NCNN. ONNX is optional. +![Screenshot_from_2023-08-29_16-40-55](https://github.com/upscayl/upscayl/assets/11874211/5c5886bd-8fbe-478b-ab50-547bf269ce4d) +2. Set the correct GPU under the ONNX tab of the settings if you can. +![Screenshot from 2023-06-19 00-01-16](https://github.com/upscayl/upscayl/assets/25067102/3f2392c5-db28-4a03-84cb-d79d6dc1c68c) +3. Load the .chn file you downloaded in the Prerequisites section by clicking File → Open in chaiNNer. +4. Select the .pth model you want to convert by clicking the button that says "Click to select a file...". +5. Select an output folder under "Base Directory". +6. Name that model by typing under "Param/Bin Name". +7. Press the Run button (▶️) on top of the window or press F5 on your keyboard. +![Screenshot_from_2023-08-29_16-53-31](https://github.com/upscayl/upscayl/assets/11874211/60fc9227-578e-4bdd-9b16-e0cfe2c7f7ec) +8. Wait for chaiNNer to finish converting. You'll get 2 files: a .bin and a .param +![Screenshot from 2023-06-18 23-49-50](https://github.com/upscayl/upscayl/assets/25067102/0c1fc3c2-1f80-4add-818c-feb4eecfe24d) +9. Open the .param file and change the first "input" on the second column and all "input"s (usually 2) in the third column to "data". +![Screenshot from 2023-06-18 23-50-51](https://github.com/upscayl/upscayl/assets/25067102/a0a020ce-107b-4e62-bf2c-3a025c569ee2) +10. Save the .param file and copy the .param and .bin file to your custom models folder named 'models'. If you don't have one, create it. +11. Open Upscayl and go to Settings → Add custom models and select your custom models folder. +![Screenshot from 2023-06-18 23-51-52](https://github.com/upscayl/upscayl/assets/25067102/cd3fda25-ca6d-4e9d-a33a-2ee61366cc8a) +![Screenshot from 2023-06-18 23-51-58](https://github.com/upscayl/upscayl/assets/25067102/16f6a401-2130-490a-981d-4487427c146a) +12. Your model should now appear at the bottom of your models list. +![Screenshot from 2023-06-18 23-52-03](https://github.com/upscayl/upscayl/assets/25067102/74e0b1cc-2ca1-4f4f-8a2c-9f261009aa2a) +13. Happy Upscayling 😄 +![Screenshot from 2023-06-18 23-53-45](https://github.com/upscayl/upscayl/assets/25067102/29bdc308-711d-4599-b1b6-ed958440f374) \ No newline at end of file diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md new file mode 100644 index 0000000..371221c --- /dev/null +++ b/docs/Troubleshooting.md @@ -0,0 +1,40 @@ +If you run into problems with Upscayl, here are a few ways to fix it. + +> [!IMPORTANT] +> You'll need a Vulkan compatible GPU to upscale images. Many CPU and iGPUs do not work but no harm in trying. +> Make sure to read [the FAQ](https://github.com/upscayl/upscayl#-faq) first to avoid getting rickrolled. + +## General Fixes +- Uninstall and Reinstall the app. +- Restart your computer. +- Try setting your [GPU ID](https://github.com/upscayl/upscayl/wiki/Guide#gpu-id) to your discrete GPU. + +## Linux Users +- Reinstall graphics drivers BUT Before doing that, run [VulkanCapsViewer](https://github.com/SaschaWillems/VulkanCapsViewer). If it reports Vulkan support, you might not need to do this. + +## Mac Users +- Make sure you're using the latest MacOS update. +### If the app doesn't work, try deleting all its files and folders: + + + +1. Open Finder → Click **Go** in the menu bar → Select **Go to Folder** from the drop-down menu → In the window that appears, type **~/Library/** and press Enter. + +2. Here, in the Library folder, find and remove all files which contain 'Upscayl'. +Here's a list of files and folders you can safely delete: +**NOTE: PLEASE DO NOT DELETE THE FOLDERS THAT DO NOT HAVE UPSCAYL IN THEIR NAME** +- **~/Library/Application Support/Upscayl** +- **~/Library/Saved Application State/org.upscayl.Upscayl.savedState/** +- **~/Library/Group Containers/W2T4W74X87.org.upscayl.Upscayl** +- **~/Library/Containers/Upscayl** (and other folders named Upscayl) +- **~/Library/Preferences/org.upscayl.Upscayl.plist/** +- **~/Library/Preferences/org.upscayl.Upscayl.helper.plist/** + +## Windows Users +- [Set the app to performance mode](https://youtube.com/watch?v=sxvs6qYHJmc) and make sure you have the right redistributables. +- Try [DirectX repair](http://blog.csdn.net/vbcom/article/details/6962388). +- [Disable switchable graphics](https://nvidia.custhelp.com/app/answers/detail/a_id/5182/~/unable-to-launch-vulkan-apps%2Fgame-on-notebooks-with-amd-radeon-igpus) if you can. (thanks @[JZeravik](https://github.com/JZeravik)!) +- [Enable hardware-accelerated GPU scheduling](https://www.howtogeek.com/756935/how-to-enable-hardware-accelerated-gpu-scheduling-in-windows-11) if you can. +- Reinstall graphics drivers BUT Before doing that, run [VulkanCapsViewer](https://github.com/SaschaWillems/VulkanCapsViewer). If it reports Vulkan support, you might not need to do this. + +# If all of the above fail, [Please click here to know how you can ask for help](https://github.com/upscayl/upscayl/wiki/%F0%9F%99%8B-How-to-ask-for-help%3F). \ No newline at end of file diff --git a/docs/favicon.svg b/docs/favicon.svg index 6a32332..0ea70e0 100644 --- a/docs/favicon.svg +++ b/docs/favicon.svg @@ -1,49 +1 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + \ No newline at end of file