High-performance, Native Cross-Platform Desktop Image Processing & Conversion Studio
Built with Python 3.11+, PySide6 (Qt6), and Pillow.

Formato is a native, professional desktop application engineered for batch image conversion, smart compression, color grading, watermarking, multi-resolution icon authoring, and multi-page PDF compilation.

Unlike browser-based wrappers or heavy electron apps, Formato runs 100% locally and natively on your machine with minimal resource overhead, thread-safe asynchronous execution, and real-time live previewing.

• Multi-Format Support: High-fidelity conversion across JPEG, PNG, WEBP, TIFF, BMP, and GIF.
• Collision-Safe Export: Never overwrites existing files — automatically resolves duplicate filenames cleanly (photo_1.webp, photo_2.webp) with atomic write protection.
• Smart Compression: Intelligent binary search algorithm to target specific file sizes (e.g. 150 KB) without manual trial-and-error.
• Aspect-Ratio Resizing:
  • Fit: Constrains inside a bounding box while strictly maintaining aspect ratio.
  • Fill / Crop: Centers and crops edges to achieve an exact dimensional canvas.
  • Stretch: Scaled directly to specified pixel bounds.
• Color & Tonal Grading: Real-time Brightness, Contrast, Saturation, and Sharpness controls.
• Artistic & Utility Filters: Grayscale, Auto-Contrast, Edge Enhancement, Sharpen, Blur, Contour, and Emboss.
• Visual Watermarking: Real-time PNG watermark overlays with opacity, size scaling, and margin offsets.
• EXIF & Metadata Engine: Preserve original camera EXIF or inject custom Author, Copyright, and Description tags.
• Thread-Safe Queue & Live Counter: Visual progress tracking, item deletion, and real-time counter (Queue · 5 Files).
• Instant Cancellation: Interrupt batch jobs safely at any moment without leaving corrupted or half-written files.

• Memory-efficient image-to-PDF compilation.
• Supports A4, A5, Letter, and Original page sizes with custom orientation (Portrait / Landscape), Fit/Fill sizing, and configurable page margins.

• Master image downsampling into multi-resolution Windows .ico files containing embedded 16×16, 32×32, 48×48, 64×64, 128×128, and 256×256 px mipmaps.

• Save and load complete workspace configurations to portable .json files.

Formato/
├── core/                       # Core Image Processing Engine
│   ├── pipeline.py             # Single unified processing pipeline (Preview & Batch)
│   ├── watermark.py            # Watermark overlay calculation & safe coordinate clamping
│   ├── pdf_builder.py          # Memory-efficient multi-page PDF generation
│   └── icon_builder.py         # Multi-size Windows .ico generator
├── models/                     # Data Models & Qt Models
│   ├── conversion_settings.py  # Dataclass with validation & clamping
│   └── queue_model.py          # Thread-safe QAbstractListModel with thumbnail caching
├── views/                      # Native Qt6 User Interface
│   ├── main_window.py          # Main Window, Sidebar navigation, and Workspaces
│   └── widgets.py              # Custom Qt Widgets & Item Delegates
├── workers/                    # Asynchronous Threading
│   ├── conversion_worker.py    # QThread batch processing with Signal/Slot communication
│   ├── preview_worker.py       # Debounced, cancellable live preview worker
│   └── pdf_worker.py           # Background PDF export worker
├── utils/                      # Utilities & Helpers
│   ├── paths.py                # Cross-platform asset, log, and runtime path resolver
│   ├── logging.py              # Centralized logging engine
│   ├── filenames.py            # Collision-proof unique output paths & atomic file writes
│   └── helpers.py              # Dimension math and conversions
├── assets/                     # Application Icons and Branding
├── tests/                      # Automated Unit Test Suite (30 Tests)
├── config.py                   # Centralized Configuration & Dark QSS Theme
├── formato.spec                # PyInstaller executable specification
└── main.py                     # Native desktop entry point

• No UI Touches from Background Threads: Worker threads communicate strictly via Qt Signals (file_progress, file_completed, overall_progress, batch_finished).
• Atomic Disk Writes: Files are written to hidden temporary files first and atomically swapped upon successful completion.
• Safe Watermark Clamping: Watermarks larger than the target canvas are scaled down dynamically, eliminating coordinate overflow bugs.

• Python 3.11 or higher
• pip

git clone https://github.com/MRThugh/Formato-Image-Converter.git
cd Formato-Image-Converter

python3 -m venv venv
# Linux / macOS:
source venv/bin/activate
# Windows:
.\venv\Scripts\activate

pip install --upgrade pip
pip install -r requirements.txt

python main.py

Formato includes a comprehensive test suite covering all image transformations, smart compression, EXIF preservation, filename collisions, watermark clamping, and PDF compilation:

python -m unittest discover -s tests -v

To build standalone, single-file or directory binaries for distribution:

pip install pyinstaller
pyinstaller formato.spec --noconfirm

The output executable will be placed in the dist/ directory:

• Windows: dist/Formato.exe
• Linux: dist/Formato
• macOS: dist/Formato.app

The repository includes a GitHub Actions workflow (.github/workflows/build.yml) that automatically:

1. Runs the full unit test suite across Python 3.11.
2. Builds native executables and installers:
   • Windows: Inno Setup installer (.exe)
   • macOS: Apple Disk Image (.dmg)
   • Linux: Standalone .tar.gz archive
3. Automatically publishes GitHub Releases with release assets whenever a version tag (e.g. v2.6.0) is pushed.

• Developer: Ali Kamrani (@MRThugh)
• Repository: MRThugh/Formato-Image-Converter
• License: Released under the MIT License.