image tweaks

docs/troubleshooting.md

@@ -3,11 +3,40 @@
 This document show most common issues and possible solutions while using the device features.
 
 - [Troubleshooting](#troubleshooting)
+    - [Images Not Displaying in EPUBs](#images-not-displaying-in-epubs)
     - [Cannot See the Device on the Network](#cannot-see-the-device-on-the-network)
     - [Connection Drops or Times Out](#connection-drops-or-times-out)
     - [Upload Fails](#upload-fails)
     - [Saved Password Not Working](#saved-password-not-working)
 
+### Images Not Displaying in EPUBs
+
+**Problem:** Some images in EPUB books show as placeholders like "[Image: filename.jpg]" instead of the actual image
+
+**Possible Causes:**
+
+1. **Progressive JPEGs are not supported**
+   - The device uses a minimal JPEG decoder optimized for embedded systems
+   - Progressive/multi-scan JPEGs cannot be decoded due to memory constraints
+   - This affects some professionally published EPUBs, especially maps and high-quality photos
+   - **Workaround:** Use Calibre or another EPUB editor to convert progressive JPEGs to baseline JPEGs
+
+2. **Unsupported image format**
+   - Only JPEG and PNG images are supported
+   - Other formats (GIF, WebP, SVG graphics) will show placeholders
+
+3. **Image extraction failed**
+   - The image file may be corrupted or the EPUB structure malformed
+   - Try re-downloading the EPUB or converting it with Calibre
+
+**How to check if an image is progressive JPEG:**
+
+```python
+from PIL import Image
+print(Image.open("image.jpg").info.get('progressive', 0))
+# Output: 1 = progressive (not supported), 0 = baseline (supported)
+```
+
 ### Cannot See the Device on the Network
 
 **Problem:** Browser shows "Cannot connect" or "Site can't be reached"