docs: add troubleshooting guide for OpenCV GUI backend errors

docs/gui-backend-issues.md

@@ -0,0 +1,114 @@
+# Troubleshooting OpenCV GUI Backend Errors
+### (`cv2.imshow`, `libGL.so.1`, HighGUI backend not available)
+
+Many Python users encounter GUI-related errors when using OpenCV functions such as  
+`cv2.imshow()`, `cv2.namedWindow()`, or `cv2.waitKey()`.  
+These errors often appear in **headless environments** such as:
+
+- CI/CD pipelines  
+- Docker containers  
+- Cloud servers  
+- WSL  
+- Google Colab  
+- SSH sessions  
+
+This guide explains:
+
+- Common GUI error messages  
+- Why these errors occur  
+- How to fix them on Linux, Windows, Docker, CI/CD, WSL  
+- When to use `opencv-python` vs. `opencv-python-headless`
+
+---
+
+## 1. Common Error Messages
+
+```
+ImportError: libGL.so.1: cannot open shared object file
+cv2.error: (-2:Unspecified error) The function is not implemented
+error: (-215:Assertion failed) size.width>0 in function 'imshow'
+HighGUI backend error: No available GUI backend
+```
+
+These errors occur because OpenCV cannot access the required **GUI backend** for creating display windows.
+
+---
+
+## 2. Why GUI Errors Occur
+
+OpenCV uses **HighGUI** for display functions (`imshow`, `waitKey`, etc.).  
+These depend on external system libraries such as:
+
+- `libGL` (OpenGL)
+- GTK or Qt
+- X11 display server
+- Cocoa (macOS)
+- Windows native GUI APIs
+
+Headless systems **do not include** these libraries, causing GUI errors when you attempt display operations.
+
+Common environments without GUI support:
+
+- GitHub/GitLab CI
+- Docker containers
+- Linux servers
+- Google Colab
+- WSL (Windows Subsystem for Linux)
+- SSH-only sessions
+
+---
+
+## 3. Fixes for Linux Desktop
+
+If you are on a regular Linux machine **with GUI**, install missing dependencies:
+
+```bash
+sudo apt update
+sudo apt install -y libgl1-mesa-glx libglib2.0-0
+sudo apt install -y libgtk2.0-dev libgtk-3-dev
+```
+## 4. Fixes for Windows
+
+Most GUI issues on Windows come from incomplete or corrupted installations.
+Reinstall OpenCV:
+```bash
+pip install --upgrade opencv-python
+pip install --upgrade opencv-contrib-python
+```
+⚠️ Important:
+Do NOT install opencv-python-headless on Windows if you want GUI support.
+
+## 5. Fixes for Headless Environments(CI, Docker, Colab, Servers)
+
+In headless environments, **cv2.imshow()** will never work.
+
+Install the headless version instead:
+```bash
+pip install opencv-python-headless
+```
+Use file-based output instead of GUI display:
+```python
+import cv2
+img = cv2.imread("image.jpg")
+cv2.imwrite("output.jpg", img)
+```
+## 6. Fix for Docker
+
+Add GUI dependencies to your Dockerfile:
+```dockerfile
+RUN apt-get update && \
+    apt-get install -y libgl1-mesa-glx libglib2.0-0
+```
+For headless images:
+```bash
+pip install opencv-python-headless
+```
+## 7. Fix For CI/CD(GitHub Actions)
+
+```
+- name: Install OpenCV GUI dependencies
+  run: |
+    sudo apt-get update
+    sudo apt-get install -y libgl1-mesa-glx libglib2.0-0
+```
+