Installation - Musfiq0/enhanced-screens-comparison GitHub Wiki

🚀 Installation

Get Enhanced Screenshot Comparison Tool up and running quickly on Windows, macOS, Linux, or Docker with these comprehensive cross-platform installation guides.

🎮 Quick Start (All Platforms)

🤖 Automatic Setup (Recommended)

The fastest way to get started on any platform:

# Clone the repository
git clone https://github.com/Musfiq0/enhanced-screens-comparison.git
cd enhanced-screens-comparison

# Run automatic setup (detects your platform)
python setup.py

The setup script will:

✅ Detect your operating system automatically
✅ Install all required dependencies
✅ Configure platform-specific settings
✅ Validate your installation
✅ Provide next steps for your platform

🖥️ Platform-Specific Launchers

Windows:

# After setup, use the Windows launcher:
START_HERE.bat

macOS/Linux:

# After setup, use the cross-platform launcher:
chmod +x start_here.sh
./start_here.sh

Docker (All Platforms):

# Use the Docker helper:
chmod +x docker_helper.sh
./docker_helper.sh

📦 Platform-Specific Installation

🪟 Windows Installation

Prerequisites

Windows 10/11 (64-bit recommended)
Python 3.8+ (Download from python.org)
Git (optional, for cloning) (Download from git-scm.com)

Step-by-Step Installation

Install Python (if not already installed):

# Download from python.org and install
# Make sure to check "Add Python to PATH" during installation

# Verify installation
python --version
pip --version

Get the Source Code:

# Option A: Clone with Git (recommended)
git clone https://github.com/Musfiq0/enhanced-screens-comparison.git
cd enhanced-screens-comparison

# Option B: Download ZIP from GitHub
# Extract to a folder and open PowerShell/Command Prompt there

Run Automatic Setup:

# This will install all dependencies and configure the system
python setup.py

Launch the Application:

# Use the Windows launcher (recommended)
START_HERE.bat

# Or run directly
python gui_app.py              # GUI mode
python comparev2.py            # Interactive CLI
python comp-cli.py --help      # Advanced CLI

Building Windows Executable

# Create a standalone .exe file
python build_exe.py

# Your executable will be in the dist/ folder

🍎 macOS Installation

Prerequisites

macOS 10.14+ (Monterey or newer recommended)
Python 3.8+ (install via Homebrew or python.org)
Xcode Command Line Tools (for some dependencies)

Step-by-Step Installation

Install Prerequisites:

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python

# Install Git
brew install git

# Install Xcode Command Line Tools
xcode-select --install

Get the Source Code:

# Clone the repository
git clone https://github.com/Musfiq0/enhanced-screens-comparison.git
cd enhanced-screens-comparison

Run Automatic Setup:

# This will install dependencies and configure for macOS
python3 setup.py

Launch the Application:

# Use the cross-platform launcher (recommended)
chmod +x start_here.sh
./start_here.sh

# Or run directly
python3 gui_app.py             # GUI mode
python3 comparev2.py           # Interactive CLI
python3 comp-cli.py --help     # Advanced CLI

Building macOS Application

# Create a .app bundle
python3 build_app.py

# Your .app will be in the dist/ folder

GUI Support on macOS

For GUI applications, you might need XQuartz:

# Install XQuartz for X11 forwarding (if needed)
brew install --cask xquartz

# For GUI in Docker containers
xhost +localhost

🐧 Linux Installation

Prerequisites

Linux distribution (Ubuntu 20.04+, CentOS 8+, or equivalent)
Python 3.8+
tkinter (often separate package on Linux)
Git

Step-by-Step Installation

Install Prerequisites:

Ubuntu/Debian:

# Update package list
sudo apt update

# Install Python and dependencies
sudo apt install python3 python3-pip python3-tk python3-dev

# Install Git
sudo apt install git

# Install build tools (for some Python packages)
sudo apt install build-essential

CentOS/RHEL/Fedora:

# For CentOS/RHEL
sudo yum install python3 python3-pip tkinter python3-devel git gcc

# For Fedora
sudo dnf install python3 python3-pip python3-tkinter python3-devel git gcc

Arch Linux:

sudo pacman -S python python-pip tk git base-devel

Get the Source Code:

# Clone the repository
git clone https://github.com/Musfiq0/enhanced-screens-comparison.git
cd enhanced-screens-comparison

Run Automatic Setup:

# This will install dependencies and configure for Linux
python3 setup.py

Launch the Application:

# Use the cross-platform launcher (recommended)
chmod +x start_here.sh
./start_here.sh

# Or run directly
python3 gui_app.py             # GUI mode
python3 comparev2.py           # Interactive CLI
python3 comp-cli.py --help     # Advanced CLI

Building Linux Binary

# Create a Linux binary/AppImage
python3 build_linux.py

# Your binary will be in the dist/ folder

GUI Support on Linux

Make sure you have a desktop environment and X11 running:

# Check if GUI is available
echo $DISPLAY

# If empty, you might be in a headless environment
# Install a desktop environment if needed

🐳 Docker Installation (All Platforms)

Docker provides a consistent environment across all platforms.

Prerequisites

Docker Desktop (Download for your platform)
Docker Compose (included with Docker Desktop)

Step-by-Step Installation

Install Docker Desktop:
- Windows: Download and install Docker Desktop for Windows
- macOS: Download and install Docker Desktop for Mac
- Linux: Install Docker Engine and Docker Compose

Get the Source Code:

# Clone the repository
git clone https://github.com/Musfiq0/enhanced-screens-comparison.git
cd enhanced-screens-comparison

Use Docker Helper Script:

# Make the script executable (macOS/Linux)
chmod +x docker_helper.sh
./docker_helper.sh

# On Windows, use PowerShell version
.\docker_helper.ps1

Or Use Docker Directly:

# Build the image
docker build -t enhanced-screenshot-comparison .

# Run CLI version
docker run -it --rm \
  -v $(pwd):/workspace \
  -v $(pwd)/Screenshots:/app/Screenshots \
  enhanced-screenshot-comparison python comparev2.py

# Run with docker-compose
docker-compose up screenshot-comparison-cli

GUI Support in Docker

Linux:

# Enable X11 forwarding
xhost +local:docker

# Run with GUI support
docker run -it --rm \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  -v $(pwd):/workspace \
  enhanced-screenshot-comparison python gui_app.py

macOS:

# Install XQuartz
brew install --cask xquartz

# Start XQuartz and enable network connections
xhost +localhost

# Run with GUI support
docker run -it --rm \
  -e DISPLAY=host.docker.internal:0 \
  -v $(pwd):/workspace \
  enhanced-screenshot-comparison python gui_app.py

Windows:

# Install VcXsrv or similar X11 server
# Configure X11 server to accept connections

# Run with GUI support (requires X11 server running)
docker run -it --rm `
  -e DISPLAY=host.docker.internal:0 `
  -v ${PWD}:/workspace `
  enhanced-screenshot-comparison python gui_app.py

🐍 Python Requirements

Supported Versions

Python 3.8+ (Recommended: Python 3.9 or higher)
Cross-Platform: Windows, macOS, Linux
Architecture: 64-bit recommended for 4K video processing

Verify Python Installation

All Platforms:

# Check Python version
python --version        # Windows
python3 --version       # macOS/Linux

# Check pip
pip --version           # Windows
pip3 --version          # macOS/Linux

# Should show Python 3.8+ and pip version information

📋 Dependencies

Core Dependencies (Required)

These are automatically installed with the setup script or pip install -r requirements.txt:

# Web and upload functionality
requests>=2.32.0
requests-toolbelt>=1.0.0

# Video/image processing (cross-platform)
opencv-python>=4.9.0
numpy>=1.26.0
pillow>=10.2.0

# Terminal output and progress (cross-platform)
colorama>=0.4.6
tqdm>=4.66.0

# GUI and drag & drop support (cross-platform)
tkinterdnd2>=0.3.0

# Build tools (for creating executables)
pyinstaller>=6.0.0
auto-py-to-exe>=2.46.0

Optional Dependencies (Enhanced Quality)

VapourSynth (Professional Video Processing)

For the highest quality processing, install VapourSynth:

Windows:

Download VapourSynth from official releases
Install the .exe installer (R65 or newer)
Install Python bindings: pip install vapoursynth awsmfunc

macOS:

# Install via Homebrew
brew install vapoursynth

# Install Python bindings
pip3 install vapoursynth awsmfunc

Linux:

# Ubuntu/Debian
sudo apt install vapoursynth python3-vapoursynth

# Or build from source for latest version
# Install Python bindings
pip3 install vapoursynth awsmfunc

Docker: VapourSynth is included in the Docker image automatically.

⚙️ Installation Verification

Using the Setup Script

# The setup script automatically validates installation
python setup.py

# Or run the validation script separately
python validate_cross_platform.py

Using Platform Launchers

Windows:

# Run the launcher and test functionality
START_HERE.bat

macOS/Linux:

# Use the cross-platform launcher
./start_here.sh

Docker:

# Use the Docker helper
./docker_helper.sh

Manual Verification

Check Core Dependencies:

# Test basic imports (all platforms)
python -c "import requests, cv2, numpy, PIL; print('✅ Core dependencies OK')"

# Test GUI dependencies
python -c "import tkinter; print('✅ GUI available')"
python -c "import tkinterdnd2; print('✅ Drag & drop available')"

# Test optional dependencies
python -c "import vapoursynth; print('✅ VapourSynth available')"

Test Video Processing:

# Run demo mode to check backends
python comparev2.py --demo

# Or test with CLI
python comp-cli.py --help

Build Tools Verification:

# Windows
python -c "import PyInstaller; print('✅ Build tools ready')"
python build_exe.py --test

# macOS
python3 build_app.py --test

# Linux
python3 build_linux.py --test

🔧 Troubleshooting Installation

Cross-Platform Issues

Python Not Found

Windows:

# If python command not found, try:
python3 --version
py --version

# Or reinstall Python with PATH option checked

macOS/Linux:

# If python not found, install via package manager:
# macOS
brew install python

# Ubuntu/Debian
sudo apt install python3 python3-pip

# CentOS/RHEL
sudo yum install python3 python3-pip

Permission Issues

All Platforms:

# Install packages for current user only
pip install --user -r requirements.txt

# Or create a virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

pip install -r requirements.txt

Platform-Specific Issues

Windows Issues

"pip is not recognized":

# Use Python module syntax
python -m pip install -r requirements.txt

# Or add Python to PATH and restart terminal

"Microsoft Visual C++ required":

# Download and install Microsoft C++ Build Tools
# https://visualstudio.microsoft.com/visual-cpp-build-tools/
# Then retry pip installation

VapourSynth Installation:

# Make sure to install VapourSynth with "Add to PATH" option
# Restart terminal after installation
python -c "import vapoursynth; print('VapourSynth working')"

macOS Issues

"Command line tools required":

# Install Xcode command line tools
xcode-select --install

# Or install full Xcode from App Store

tkinter not available:

# Install Python with tkinter support
brew install python-tk

# Or use system Python
/usr/bin/python3 -m tkinter

Permission denied on scripts:

# Make scripts executable
chmod +x start_here.sh
chmod +x docker_helper.sh

Linux Issues

tkinter not available:

# Ubuntu/Debian
sudo apt install python3-tk

# CentOS/RHEL
sudo yum install tkinter

# Fedora
sudo dnf install python3-tkinter

Build tools missing:

# Ubuntu/Debian
sudo apt install build-essential python3-dev

# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install python3-devel

# Fedora
sudo dnf groupinstall "Development Tools"
sudo dnf install python3-devel

GUI not working (headless server):

# Install virtual display for headless GUI
sudo apt install xvfb

# Run with virtual display
xvfb-run -a python3 gui_app.py

Docker Issues

Docker not found:

# Install Docker Desktop for your platform
# https://www.docker.com/products/docker-desktop

# Verify installation
docker --version
docker-compose --version

Permission denied (Linux):

# Add user to docker group
sudo usermod -aG docker $USER

# Logout and login again, or run:
newgrp docker

GUI not working in Docker:

# Linux: Enable X11 forwarding
xhost +local:docker

# macOS: Install and configure XQuartz
brew install --cask xquartz
# Enable "Allow connections from network clients" in XQuartz preferences

# Windows: Install VcXsrv or similar X11 server

Package-Specific Issues

tkinterdnd2 Installation Problems

# Try alternative installation methods
pip install tkinterdnd2 --force-reinstall --no-cache-dir

# If still fails, the app will work without drag & drop
# (GUI will show a warning but remain functional)

OpenCV Installation Issues

# Try alternative OpenCV packages
pip uninstall opencv-python
pip install opencv-python-headless

# Or install system OpenCV (Linux)
sudo apt install python3-opencv

VapourSynth Python Binding Issues

# Make sure VapourSynth system package is installed first
# Then install Python bindings
pip install vapoursynth

# If still not working, the app will fall back to OpenCV

🏗️ Build Environment Setup

For Creating Executables

If you plan to build standalone executables:

# Install all dependencies including build tools
pip install -r requirements.txt

# Verify PyInstaller
python -c "import PyInstaller; print('PyInstaller ready')"

# Test build
python build_exe.py

Development Environment

For contributing to the project:

# Install in development mode
pip install -e .

# Install additional development tools
pip install black flake8 pytest

# Run tests (if available)
pytest

🚀 First Run

Quick Test (All Platforms)

After installation, test the application:

Windows:

# Use the Windows launcher (recommended)
START_HERE.bat

# Or run directly
python gui_app.py              # GUI mode
python comparev2.py            # Interactive CLI
python comp-cli.py --help      # Advanced CLI help

macOS/Linux:

# Use the cross-platform launcher (recommended)
./start_here.sh

# Or run directly
python3 gui_app.py             # GUI mode
python3 comparev2.py           # Interactive CLI
python3 comp-cli.py --help     # Advanced CLI help

Docker:

# Use Docker helper for interactive setup
./docker_helper.sh

# Or run specific modes
docker run -it enhanced-screenshot-comparison python comparev2.py

Interface Options

GUI Mode: Visual drag & drop interface
- Best for: Beginners, visual users
- Features: Drag & drop, visual settings, progress bars
Interactive CLI: Guided command-line interface
- Best for: Power users who want guidance
- Features: Step-by-step prompts, full functionality
Advanced CLI: Professional command-line interface
- Best for: Automation, CI/CD, batch processing
- Features: Full argument support, configuration files

Running Your First Comparison

GUI Mode:

Launch GUI: START_HERE.bat (Windows) or ./start_here.sh (macOS/Linux)
Drag & drop video files into the interface
Configure settings as needed
Click "Generate Screenshots"
Optionally upload to slow.pics

CLI Mode:

Run: python comparev2.py (or python3 on macOS/Linux)
Follow the guided prompts
Select videos when prompted
Choose settings
Let the tool process and upload

📁 Directory Structure After Installation

enhanced-screenshot-comparison/
├── � Application Files
│   ├── gui_app.py                    # Cross-platform GUI application
│   ├── comparev2.py                  # Interactive CLI tool
│   ├── comp-cli.py                   # Advanced CLI interface
│   └── icon.ico                      # Application icon
├── �️ Setup & Validation
│   ├── setup.py                      # Automatic cross-platform setup
│   └── validate_cross_platform.py    # Installation validator
├── �📦 Dependencies
│   └── requirements.txt              # Python dependencies
├── 🚀 Platform Launchers
│   ├── START_HERE.bat                # Windows launcher
│   ├── start_here.sh                 # macOS/Linux launcher
│   ├── run_gui.bat                   # Windows GUI launcher
│   └── run_advanced_cli.bat          # Windows CLI launcher
├── 🐳 Docker Support
│   ├── Dockerfile                    # Container build instructions
│   ├── docker-compose.yml            # Container orchestration
│   ├── docker_helper.sh              # Docker management (Unix)
│   ├── docker_helper.ps1             # Docker management (Windows)
│   └── .dockerignore                 # Docker ignore patterns
├── 🔨 Build System
│   ├── build_exe.py                  # Windows executable builder
│   ├── build_app.py                  # macOS app bundle builder
│   ├── build_linux.py               # Linux binary builder
│   ├── Makefile                      # Cross-platform build automation
│   ├── screenshot_comparison.spec    # PyInstaller config
│   └── build.bat                     # Windows build script
├── ⚙️ Configuration
│   ├── sample_config.json            # Example CLI configuration
│   └── version_info.txt              # Version metadata
├── 📸 Output (Created on first run)
│   └── Screenshots/                  # Generated screenshots
└── 📖 Documentation
    ├── README.md                     # Main documentation
    ├── PROJECT_STRUCTURE.md          # Project overview
    ├── Makefile                      # Build automation help
    └── enhanced-screens-comparison.wiki/
        ├── Installation.md           # This installation guide
        ├── Usage.md                  # Usage instructions
        ├── Features.md               # Feature documentation
        ├── Configuration.md          # Configuration guide
        ├── Advanced-CLI.md           # Advanced CLI guide
        └── ...                       # Additional wiki pages

🎯 Next Steps

After successful installation:

📚 Learn the Basics

Usage Guide - Learn the basic workflow and interface options
Features - Discover all available features and capabilities
Configuration - Customize settings for your workflow

🎮 Choose Your Interface

GUI Interface - Visual drag & drop interface
Interactive CLI - Guided command-line interface
Advanced CLI - Professional automation interface

🚀 Advanced Topics

Build System - Create executables for your platform
Docker Usage - Containerized deployment
Contributing - Help improve the project

💡 Platform-Specific Tips

Windows Users

Use START_HERE.bat for the easiest experience
Install VapourSynth for professional video quality
Build executables with python build_exe.py for distribution

macOS Users

Use start_here.sh for the native experience
Install XQuartz if you plan to use Docker GUI
Build app bundles with python3 build_app.py

Linux Users

Install python3-tk for GUI support
Use virtual environments to avoid dependency conflicts
Build AppImages with python3 build_linux.py

Docker Users

Use docker_helper.sh for easy container management
Mount volumes to persist screenshots and config
Enable X11 forwarding for GUI support

🏆 Best Practices

Performance

8GB+ RAM recommended for 4K video processing
SSD storage for faster video reading
Multi-core CPU for parallel processing

Workflow

Organize videos in separate folders before processing
Use consistent naming for easy screenshot identification
Save configurations for repeated workflows

Quality

Install VapourSynth for highest quality processing
Use lossless intermediate formats when possible
Configure crop settings to remove black bars

Installation should be smooth and straightforward on any platform. If you encounter issues, check the troubleshooting section or open an issue on GitHub! 🛠️

🆘 Getting Help

Documentation

Wiki Home - Complete documentation
FAQ - Common questions and solutions
Troubleshooting - Platform-specific issues

Community

GitHub Issues - Report bugs or request features
GitHub Discussions - Community support and questions
Wiki - Comprehensive guides and examples

Quick Commands for Help

# Show application help
python comp-cli.py --help

# Run validation
python validate_cross_platform.py

# Check installation
python setup.py

# Demo mode
python comparev2.py --demo