📦 Installation Guide

Minimum Requirements

• Operating System: Windows 7+, macOS 10.12+, or Linux (Ubuntu/Debian/CentOS/Fedora etc)
• CPU: At least 2 cores (dual-core or better required)
• Python: Version 3.10 or higher
• RAM: At least 4GB
• Storage: 1GB for application + output of single spritesheet processing (5GB+ recommended for batch processing)
• Internet Access: Required for downloading dependencies and updates

Recommended Requirements

• Operating System: Windows 10/11 (64-bit), macOS 11+ (Big Sur or later), or recent Linux (Ubuntu 20.04+/Fedora 36+)
• CPU: Quad-core or better
• Python: Version 3.12 or higher (64-bit)
• RAM: 8GB or more (16GB+ recommended for batch processing large atlases)
• Storage: SSD with 10GB+ free space for faster processing speeds but a regular hard drive will suffice
• Internet Access: Required for downloading dependencies and updates

Python Installation

🪟 Windows

1. Download Python from python.org.
2. Important: During installation, check the box for "Add Python to PATH".
3. Complete the installation.
4. Open Command Prompt and verify installation:

   python --version

   If you see a version number (e.g., Python 3.12.3), Python is installed correctly.

🍎 macOS

1. Recommended: Install Homebrew if you haven't already:

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

2. Install Python:

   brew install python

3. Verify installation:

   python3 --version

🐧 Linux (Ubuntu/Debian)

1. Update package lists:

   sudo apt update

2. Install Python and pip:

   sudo apt install python3 python3-pip

3. Verify installation:

   python3 --version

Installing Python Dependencies

Using requirements.txt (Recommended)

🪟 Windows:

1. Double-click or run setup/setup_windows.bat from the project folder. This will attempt to install all required dependencies automatically.
2. If you prefer manual steps, open a terminal or command prompt, navigate to the project root directory, and run:

   pip install -r setup/requirements.txt

   If you encounter permission errors, try:

   python -m pip install --user -r setup/requirements.txt

🍎 macOS:

1. Open Terminal and run the setup script:

   bash setup/setup_macOSX.sh

   This will attempt to install all required dependencies automatically, please note that the .sh script for OSX is experimental and not tested by me.
2. If you prefer manual steps, navigate to the project root directory and run:

   pip install -r setup/requirements.txt

   If you encounter permission errors, try:

   python3 -m pip install --user -r setup/requirements.txt

🐧 Linux:

1. Open a terminal, navigate to the project root directory, and run:

   pip install -r setup/requirements.txt

   If you encounter permission errors, try:

   python3 -m pip install --user -r setup/requirements.txt

Full Manual Installation

If you prefer, you can install packages individually:

pip install certifi charset-normalizer colorama idna numpy pillow psutil requests tqdm urllib3 Wand tkinter py7zr

Note: On some Linux systems, you may need to install tkinter separately (see Troubleshooting).

Package Details

• Pillow (PIL): Image processing and manipulation
• Wand: Python binding for ImageMagick
• NumPy: Numerical operations for image arrays
• Tkinter: GUI framework (usually included with Python)
• Requests: HTTP library for update checking
• certifi: Root certificates for validating the trustworthiness of SSL certificates
• charset-normalizer: Encoding detection for text files and web content
• colorama: Cross-platform colored terminal text
• idna: Internationalized Domain Names in Applications (IDNA) support
• psutil: System and process utilities (used for resource monitoring)
• tqdm: Progress bar for loops and CLI operations
• urllib3: HTTP client for Python (dependency of requests)

ImageMagick Setup

ImageMagick is required for GIF processing and optimization.

🪟 Windows (Manual)

1. Download ImageMagick from imagemagick.org.
2. Choose the version matching your system (64-bit recommended).
3. Run the installer.
4. Important: During installation, check:
   • "Install development headers and libraries for C and C++"
   • "Add application directory to your system PATH"
5. After installation, open a new Command Prompt and verify:

   magick --version

   If you see version info, ImageMagick is installed.

🍎 macOS (Manual)

1. Install via Homebrew:

   brew install imagemagick

2. Verify:

   magick --version

🐧 Linux (Manual)

Ubuntu/Debian:

sudo apt update
sudo apt install imagemagick libmagickwand-dev

Fedora:

sudo dnf install ImageMagick ImageMagick-devel

CentOS/RHEL:

sudo yum install ImageMagick ImageMagick-devel

Verify Installation:

magick --version

Clone Repository (For Developers)

1. Open a terminal or command prompt.
2. Run:

   git clone https://github.com/MeguminBOT/TextureAtlas-to-GIF-and-Frames.git
   cd TextureAtlas-to-GIF-and-Frames