This README provides a comprehensive guide to the MCE OLED Toolset, specifically designed for processing, previewing, and managing monochrome splash images for OLED displays.

---

Project Overview

This toolset consists of two primary Python applications:

1. MCE.OLED.EDITOR: A powerful image processing utility to convert standard images into MCE OLED format.
2. MCE.OLED.GALLERY: A curated browser for navigating and previewing large libraries of splash screens in a simulated hardware environment.

---

File Breakdowns

1. MCE.OLED.EDITOR.py

The Editor is the "foundry" of the project. It handles the heavy lifting of converting high-resolution, color images into the 1-bit (monochrome) format required by FlipperMCE / GCMCE.

• Drag-and-Drop Interface: Utilizes tkinterdnd2 to allow users to simply drop any image file into the window for immediate processing.
• Advanced Dithering: Implements multiple algorithms (Floyd-Steinberg and Ordered Dithering) to maintain visual detail when downscaling from 16 million colors to just two.
• Automatic Resizing: Targets the standard $128 \times 64$ resolution (or custom dimensions defined in the script), ensuring aspect ratios are maintained via smart padding or cropping.
• Data Export: Generates the raw byte arrays or C-style headers needed for firmware integration.

2. MCE.OLED.GALLERY.py

The Gallery serves as a specialized browser for exploring the database.json catalog of existing splash screens.

• Hardware Preview: Instead of showing a raw flat image, it overlays the splash screens onto a hardware frame (gcmcepr.png), giving a "What You See Is What You Get" (WYSIWYG) look.
• Database Integration: It parses a JSON-based database to allow for rapid searching and categorization of images.
• Resource Management: Uses a custom resource_path logic to ensure that even when compiled into an executable, it can find its internal assets (icons and frames) within the temporary PyInstaller _MEIPASS directory.

---

Technical Requirements

To run these scripts from source, you will need Python 3.10+ and the following dependencies:

Library	Purpose
Pillow (PIL)	Image manipulation and pixel processing.
NumPy	High-performance array operations for dithering logic.
tkinterdnd2	Enables the Drag-and-Drop functionality for the UI.
PyInstaller	(Optional) Required only if you wish to build standalone .exe files.

---

Installation & Usage

1. Environment Setup

It is recommended to use a virtual environment to keep your system clean:

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install pillow numpy tkinterdnd2

### 2. Running the Apps

Launch the scripts directly using the Python interpreter:

• To edit/convert images: python MCE.OLED.EDITOR.py
• To browse the collection: python MCE.OLED.GALLERY.py

---

Building Standalone Executables

If you want to build these tools yourself as .exe files so others don't need Python installed, use PyInstaller.

Note: Because these apps rely on external assets (like .png frames or .json databases), you must "bundle" these files into the executable using the --add-data flag.

For the Editor

python -m PyInstaller --onefile --windowed --add-data "gcmcepr.png;." --icon="edit.ico" MCE.OLED.EDITOR.py

For the Gallery

python -m PyInstaller --onefile --windowed --add-data "gcmcepr.png;." --add-data "database.json;." --icon="gallr.ico" MCE.OLED.GALLERY.py

Flag Explanation:

• --onefile: Packs everything into a single executable.
• --windowed: Prevents a black console window from opening in the background.
• --add-data "file;destination": Tells PyInstaller to put the file inside the internal app folder. Use ; on Windows and : on Linux/macOS.

---

Common Troubleshooting

• TkinterDnD Errors: If the app fails to start with a "TclError," ensure you have installed tkinterdnd2 correctly. On some Linux distributions, you may also need the python3-tk system package.
• Missing Images: Ensure gcmcepr.png is in the same folder as the script when running locally, or properly bundled when building the EXE.