Merge pull request #81 from SkwalExe/troubleshooting

Add troubleshooting instructions in the documentation
SkwalExe · Aug 5, 2024 · e1120b2 · e1120b2
2 parents 7dafe48 + 9c2e3cb
commit e1120b2
Show file tree

Hide file tree

Showing 10 changed files with 64 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -51,6 +51,7 @@ echo 'export PATH=$PATH:~/.local/bin' >> ~/.zshrc; zsh
 ```
 
 # Features 🌟
+
 ### **⚡ Multi-threaded**
 Fractalistic leverages parallel processing for complex arithmetic operations, enabling smooth navigation and rapid rendering.
 ### **🔢 High Precision Arithmetics**
@@ -64,30 +65,21 @@ Fractalistic offers a robust command system that goes beyond simple fractal navi
 ### **⚙️  Modular Rendering Engine**
 Fractalistic's underlying rendering engine is highly modular. The integrated command system enables you to inspect and modify technical parameters, allowing you to explore beyond the basic Mandelbrot and Julia sets. The combination of adjustable parameters makes the number of possible fractals effectively infinite.
 
-# Screenshots
-
-![Screenshot 0](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot0.png)
-
-![Screenshot 1](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot1.png)
+# Screenshots 🌟
 
-![Screenshot 3](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot3.png)
+Here is some eye candy that I generated while creating this app!
 
-![Screenshot 2](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot2.png)
+[💎 For more screenshots, visit the documentation!](https://fractalistic.skwal.net/screenshots.html)
 
-![Screenshot 4](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot4.png)
 
-![Screenshot 5](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot5.png)
-
-![Screenshot 6](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot6.png)
+![Screenshot 0](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot0.png)
 
-![Screenshot 7](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot7.png)
+![Screenshot 1](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot1.png)
 
-![Screenshot 8](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot8.png)
+![Screenshot 4](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot4.png)
 
 ![Screenshot 9](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot9.png)
 
-![Screenshot 10](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot10.png)
-
 ![Screenshot 11](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot11.png)
 
 ![Screenshot 12](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/screenshot12.png)

diff --git a/assets/banner.png b/assets/banner.png
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -30,6 +30,7 @@ export default defineConfig({
                 text: 'Introduction',
                 items: [
                     { text: '📥 Getting Started', link: '/getting-started' },
+                    { text: '❗  Color Issues', link: '/color-issues' },
                     { text: '🌟 Screenshots', link: '/screenshots' }
                 ]
             },

diff --git a/docs/src/color-issue1.png b/docs/src/color-issue1.png
diff --git a/docs/src/color-issue2.png b/docs/src/color-issue2.png
diff --git a/docs/src/color-issues.md b/docs/src/color-issues.md
@@ -0,0 +1,40 @@
+# Color Issues ❗ {#color-issues}
+
+**In good conditions, the app should use 24-bit colors which looks like this:**
+
+![Normal colors](./normal-colors.png)
+
+However, it is possible that when you open the app, the colors are not displaying correctly. In this case, it can look something like this if only 4-bits ANSI colors are used:
+
+![Color issue 1](./color-issue1.png)
+
+It can also look like this if only 8-bits ANSI colors are used :
+
+![Color issue 2](./color-issue2.png)
+
+
+If the colors are not displaying correctly, ensure that your terminal supports 24-bit colors (truecolor). You can verify this by copying and pasting the following command into your terminal:
+
+
+```bash
+curl -sLo- https://raw.githubusercontent.com/SkwalExe/fractalistic/main/test-truecolor.sh | bash
+```
+
+> Please note that running `curl ... | bash` commands can be dangerous and is generally considered a bad practice unless you are certain that the script originates from a trustworthy source.
+
+You should see smooth output similar to the screenshot below. If not, consider updating your terminal or switching to a more modern terminal that supports 24-bit colors.
+
+![Preview](./truecolor.png)
+
+If your terminal supports 24-bit colors but the colors are still not displaying correctly, you might need to set the following environment variable when running the app:
+
+```bash
+COLORTERM=truecolor fractalistic
+```
+
+Additionally, consider adding this to your `~/.bashrc` or `~/.zshrc` to make the change permanent:
+
+```bash
+export COLORTERM=truecolor
+```
+
diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md
@@ -37,3 +37,17 @@ fractalistic
 ```
 
 ![Preview](https://raw.githubusercontent.com/SkwalExe/fractalistic/main/assets/banner.png)
+
+## Troubleshooting install errors 
+
+To perform high precision arithmetics, Fractalistic use GMPY2. This dependency can sometimes prevent the installation to succeed because of missing system libraries.
+The [GMPY2 documentation](https://gmpy2.readthedocs.io/en/latest/install.html) provides a solution to this problem on debian systems.
+
+> If pre-compiled binary wheels aren’t available for your platform, the pip will fallback to installation from sources. In this case you will need to have required libraries (GMP, MPFR and MPC) already installed on your system, along with the include files for those libraries. On Debian you can install them systed-wide with:
+> 
+> ```bash
+> sudo apt install libgmp-dev libmpfr-dev libmpc-dev
+> ```
+
+For windows, I can suggest [this StackOverflow post](https://stackoverflow.com/questions/59471761/python-3-7-unable-to-install-gmpy2-in-a-venv-in-windows-10). 
+I do not use Windows so I cannot check if this solution works, but you should give it a try.
diff --git a/docs/src/normal-colors.png b/docs/src/normal-colors.png
diff --git a/docs/src/truecolor.png b/docs/src/truecolor.png
diff --git a/src/fractalistic/colors.py b/src/fractalistic/colors.py
@@ -10,8 +10,6 @@ def get_intensity(i: int) -> int:
 # These colors are picked from UF6
 # https://www.ultrafractal.com/
 BLUE_BROWN = [
-    Color(69, 33, 19),
-    Color(28, 10, 29),
     Color(12, 4, 50),
     Color(7, 7, 76),
     Color(3, 10, 103),
@@ -26,6 +24,8 @@ def get_intensity(i: int) -> int:
     Color(207, 131, 3),
     Color(156, 90, 3),
     Color(109, 55, 6),
+    Color(69, 33, 19),
+    Color(28, 10, 29),
 ]