Installation Guide

This guide provides detailed instructions for installing GUI Image Studio on different platforms and environments.

System Requirements

Minimum Requirements: - Python 3.8 or later - 512 MB RAM - 100 MB disk space - Display resolution: 1024x768

Recommended Requirements: - Python 3.10 or later - 2 GB RAM - 500 MB disk space - Display resolution: 1920x1080 or higher

Supported Operating Systems: - Windows 10/11 - macOS 10.14+ - Linux (Ubuntu 18.04+, CentOS 7+, or equivalent)

Installation Methods

Method 1: Install from PyPI (Recommended)

The easiest way to install GUI Image Studio:

pip install gui-image-studio

This installs the latest stable version with all required dependencies.

Method 2: Install from Source

For the latest development version:

git clone https://github.com/stntg/gui-image-studio.git
cd gui-image-studio
pip install -e .

Method 3: Development Installation

For contributors and developers:

git clone https://github.com/stntg/gui-image-studio.git
cd gui-image-studio
pip install -e .[dev,test,docs]

This includes all development dependencies.

Dependencies

Required Dependencies:

Pillow >= 8.0.0          # Image processing
threepanewindows >= 1.0.0 # Window layout system

Optional Dependencies:

customtkinter >= 5.0.0   # Modern UI components

Development Dependencies:

pytest >= 7.0            # Testing framework
black                     # Code formatting
flake8                    # Code linting
mypy                      # Type checking
sphinx >= 5.0            # Documentation

Platform-Specific Instructions

Windows Installation

Using pip (Recommended):

pip install gui-image-studio

Using conda:

conda install -c conda-forge pillow
pip install gui-image-studio

Common Windows Issues:

1. Missing Visual C++ Redistributable: Download from Microsoft’s website if you encounter compilation errors.

2. Permission Issues: Run Command Prompt as Administrator or use:

   pip install --user gui-image-studio
   

3. PATH Issues: Ensure Python Scripts directory is in your PATH.

macOS Installation

Using pip:

pip3 install gui-image-studio

Using Homebrew:

brew install python
pip3 install gui-image-studio

macOS-Specific Notes:

1. Xcode Command Line Tools: May be required for some dependencies:

   xcode-select --install
   

2. Security Warnings: You may need to allow the application in System Preferences > Security & Privacy.

Linux Installation

Ubuntu/Debian:

# Install system dependencies
sudo apt-get update
sudo apt-get install python3-pip python3-tk python3-dev

# Install GUI Image Studio
pip3 install gui-image-studio

CentOS/RHEL/Fedora:

# Install system dependencies
sudo yum install python3-pip python3-tkinter python3-devel
# or for newer versions:
sudo dnf install python3-pip python3-tkinter python3-devel

# Install GUI Image Studio
pip3 install gui-image-studio

Arch Linux:

# Install system dependencies
sudo pacman -S python-pip tk python-pillow

# Install GUI Image Studio
pip install gui-image-studio

Virtual Environment Setup

Creating a Virtual Environment:

# Create virtual environment
python -m venv gui-image-studio-env

# Activate (Linux/macOS)
source gui-image-studio-env/bin/activate

# Activate (Windows)
gui-image-studio-env\Scripts\activate

# Install GUI Image Studio
pip install gui-image-studio

Using conda:

# Create conda environment
conda create -n gui-image-studio python=3.10
conda activate gui-image-studio

# Install dependencies
conda install pillow
pip install gui-image-studio

Verification

Test Installation:

import gui_image_studio
print(f"GUI Image Studio version: {gui_image_studio.__version__}")

Test CLI Commands:

# Test designer launch
gui-image-studio-designer --help

# Test sample creation
gui-image-studio-create-samples --help

# Test image generation
gui-image-studio-generate --help

Test Basic Functionality:

from gui_image_studio import get_image, create_sample_images

# Create sample images
create_sample_images()

# Load a sample image
image = get_image("sample_icon", framework="tkinter")
print("Installation successful!")

Troubleshooting

Common Installation Issues

1. ImportError: No module named ‘tkinter’

Linux Solution:

# Ubuntu/Debian
sudo apt-get install python3-tk

# CentOS/RHEL
sudo yum install tkinter

2. PIL/Pillow Installation Issues

# Upgrade pip first
pip install --upgrade pip

# Install/upgrade Pillow
pip install --upgrade Pillow

3. Permission Denied Errors

# Install for current user only
pip install --user gui-image-studio

4. SSL Certificate Errors

# Use trusted hosts
pip install --trusted-host pypi.org --trusted-host pypi.python.org gui-image-studio

5. Network/Proxy Issues

# Configure proxy
pip install --proxy http://user:password@proxy.server:port gui-image-studio

Version Management

Check Current Version:

pip show gui-image-studio

Upgrade to Latest Version:

pip install --upgrade gui-image-studio

Install Specific Version:

pip install gui-image-studio==1.1.0

Downgrade Version:

pip install gui-image-studio==1.0.0

Uninstallation

Remove GUI Image Studio:

pip uninstall gui-image-studio

Clean Uninstall (remove all dependencies):

pip uninstall gui-image-studio Pillow threepanewindows

Remove Virtual Environment:

# Deactivate first
deactivate

# Remove directory
rm -rf gui-image-studio-env

Docker Installation

Using Docker:

FROM python:3.10-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    python3-tk \
    && rm -rf /var/lib/apt/lists/*

# Install GUI Image Studio
RUN pip install gui-image-studio

# Set working directory
WORKDIR /app

# Copy your application
COPY . .

# Run your application
CMD ["python", "your_app.py"]

Docker Compose Example:

version: '3.8'
services:
  gui-image-studio:
    build: .
    volumes:
      - ./images:/app/images
      - ./output:/app/output
    environment:
      - DISPLAY=${DISPLAY}
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix

CI/CD Integration

GitHub Actions Example:

name: Test GUI Image Studio
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8, 3.9, '3.10', 3.11]

    steps:
    - uses: actions/checkout@v4
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}

    - name: Install system dependencies
      run: |
        sudo apt-get update
        sudo apt-get install python3-tk

    - name: Install GUI Image Studio
      run: |
        pip install gui-image-studio

    - name: Test installation
      run: |
        python -c "import gui_image_studio; print('Success!')"

Travis CI Example:

language: python
python:
  - "3.8"
  - "3.9"
  - "3.10"
  - "3.11"

before_install:
  - sudo apt-get update
  - sudo apt-get install python3-tk

install:
  - pip install gui-image-studio

script:
  - python -c "import gui_image_studio"

Getting Help

If you encounter installation issues:

1. Check the troubleshooting section above

2. Search existing issues: https://github.com/stntg/gui-image-studio/issues

3. Create a new issue with: - Your operating system and version - Python version - Complete error message - Installation method used

4. Join community discussions

Diagnostic Information:

When reporting issues, include this diagnostic information:

import sys
import platform
import pip

print(f"Python version: {sys.version}")
print(f"Platform: {platform.platform()}")
print(f"Architecture: {platform.architecture()}")

try:
    import gui_image_studio
    print(f"GUI Image Studio version: {gui_image_studio.__version__}")
except ImportError as e:
    print(f"Import error: {e}")

Next Steps

After successful installation:

1. Read the Quick Start Guide: First Steps

2. Explore the Interface: Interface Overview

3. Try the Examples: Examples

4. Check the API Reference: API Reference