📦 Installation Guide

Complete installation instructions for TextureAtlas to GIF and Frames on all supported platforms

Note: TextureAtlas Toolbox v2.0.0 uses a fully Qt-based (PySide6) user interface. This guide will walk you through installing and setting up the application on your system. macOS and Linux users or developers can refer to the detailed manual installation sections.

📝 System Requirements

Minimum Requirements

Operating System: Windows 10+, macOS 11+, or Linux (Ubuntu 20.04+/Debian 11+/Fedora 36+)
CPU: At least 2 cores (dual-core or better required)
Python: Version 3.14 or higher
RAM: At least 8GB
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 22.04+/Fedora 38+)
CPU: Quad-core or better
Python: Version 3.14 or higher (64-bit)
RAM: 16GB or more (32GB+ recommended for batch processing large atlases or Adobe Animate spritemaps)
Storage: SSD with 10GB+ free space for faster processing speeds (a regular hard drive will suffice for smaller workloads)
Internet Access: Required for downloading dependencies and updates

⚠️ Important Notices

32-bit operating systems are not officially supported and will not receive troubleshooting help.

Operating systems below macOS 11, Windows 10, and older Linux distributions are not officially supported and will not receive troubleshooting help.

Python versions below 3.14 are not officially supported and will not receive troubleshooting help.

🚀 Normal Install (Windows only)

⚠️ Antivirus False Positives: The Windows executable releases may be flagged as malware by antivirus software. This is a common false positive for Python applications compiled with tools like Nuitka. The application is open-source and safe—you can verify the code yourself. Add an exception for the executable or use the Manual Installation method to run from source.

Go to the GitHub Releases page.
Download the latest release ZIP or 7z file.
Extract all files to a folder of your choice (e.g., C:\TextureAtlasToolbox).
Run TextureAtlas Toolbox.exe.

That's it! If you encounter any issues, check the Troubleshooting section below.

🚀 Manual Installation

For the Advanced users, developers or Mac/Linux users:

This will guide you through how to install Python and the required dependencies to run the app directly from the .py scripts.

Python Installation

🪟 Windows

Download Python from python.org.
Important: During installation, check the box for "Add Python to PATH".
Complete the installation.
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

Recommended: Install Homebrew if you haven't already:

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

Install Python:
```
brew install python
```
Verify installation:
```
python3 --version
```

🐧 Linux (Ubuntu/Debian)

Update package lists:
```
sudo apt update
```
Install Python and pip:
```
sudo apt install python3 python3-pip
```
Verify installation:
```
python3 --version
```

Installing Python Dependencies

Using requirements.txt (Recommended)

🪟 Windows:

Double-click or run setup/setup_windows.bat from the project folder. This will attempt to install all required dependencies automatically.
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:

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.
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:

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 PySide6 certifi charset-normalizer colorama idna numpy pillow psutil requests tqdm urllib3 Wand py7zr

Package Details

PySide6: Qt 6 bindings for Python (GUI framework)
Pillow (PIL): Image processing and manipulation
Wand: Python binding for ImageMagick
NumPy: Numerical operations for image arrays
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)

Download ImageMagick from imagemagick.org.
Choose the version matching your system (64-bit recommended).
Run the installer.
Important: During installation, check:
- "Install development headers and libraries for C and C++"
- "Add application directory to your system PATH"
After installation, open a new Command Prompt and verify:
```
magick --version
```
If you see version info, ImageMagick is installed.

🍎 macOS (Manual)

Install via Homebrew:
```
brew install imagemagick
```
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)

Open a terminal or command prompt.

Run:

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

🔧 Troubleshooting Installation & Common Errors

If you run into installation or startup problems, use this section to diagnose and fix the most common issues. These solutions apply to both source and (where relevant) .exe versions.

Python Not Recognized

Windows: Run setup/setup_windows.bat or reinstall Python 3.14+ and ensure "Add Python to PATH" is checked.
macOS: Run setup/setup_macOSX.sh or install Python via Homebrew. (The setup script for macOS is experimental)
Linux: Install Python 3.14+ using your package manager or build from source.

Missing Packages

Install all dependencies:

pip install -r setup/requirements.txt

ImageMagick Errors

Ensure ImageMagick is installed and added to your PATH.
On Windows, verify the ImageMagick folder exists or reinstall manually.

"No module named 'PIL'"

Install Pillow:

pip install Pillow

PySide6 Installation Issues

If you encounter issues with PySide6:

pip install --upgrade PySide6

On Linux, you may need to install additional Qt dependencies for your distribution.

Verifying Installation

Start the application:
```
cd src
python Main.py
```
Ensure the GUI opens without errors.
Test loading a sample texture atlas and exporting a GIF.

Updating the Application

The app checks for updates on startup.
If notified, download the latest release and replace your files.

Last updated: December 18, 2025 - Version 2.0.0