gui-image-studio 1.0.1

GUI Image Studio - Complete toolkit for creating, embedding, and managing images in Python GUI applications

GUI Image Studio

A comprehensive Python toolkit for creating, embedding, and managing images in Python GUI applications with support for tkinter and customtkinter.

📚 Documentation

📖 Full Documentation - Complete guides, API reference, and examples

Quick links:

• 🚀 Quick Start Guide
• 📖 API Reference
• 💡 Examples
• 🛠️ Installation Guide

Features

• 🎨 Visual Image Studio GUI - Create and edit images with drawing tools
• 🖼️ Convert images to base64 encoded strings
• 📁 Batch process entire folders of images
• 🎨 Support for multiple GUI frameworks (tkinter, customtkinter)
• 🔧 Image transformations (resize, rotate, flip, tint, contrast, saturation)
• 📦 Generate embedded Python modules for easy distribution
• 🎬 Animated GIF support
• 🎯 High-quality compression options
• 📝 Sample image generation for testing
• 👁️ Real-time code preview and generation

Installation

From PyPI (when published)

pip install gui-image-studio

From Source

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

Quick Start

Image Studio GUI

Launch the visual image studio to create images with drawing tools:

# Launch the studio GUI
python -m gui_image_studio

# Or use the launcher script
python launch_designer.py

# Or programmatically
python -c "import gui_image_studio; gui_image_studio.launch_designer()"

The Image Studio GUI provides:

• Drawing tools (brush, eraser, shapes, text)
• Image transformations and filters
• Multiple image management
• Real-time preview
• Code generation with preview
• Export capabilities

Basic Usage

from gui_image_studio import get_image, embed_images_from_folder

# Get a single image with transformations
image = get_image(
    "my_image.png",
    framework="tkinter",
    size=(64, 64),
    theme="default"
)

# Embed all images from a folder
embed_images_from_folder(
    folder_path="images/",
    output_file="embedded_images.py",
    compression_quality=85
)

Using Embedded Images

# After embedding images, use them in your GUI
import gui_image_studio
import tkinter as tk

root = tk.Tk()

# Load embedded image with transformations
photo = gui_image_studio.get_image(
    "my_image.png",
    framework="tkinter",
    size=(100, 100),
    theme="default"
)
label = tk.Label(root, image=photo)
label.pack()

root.mainloop()

Command Line Interface

# Launch the Image Studio GUI
python -m gui_image_studio
# Or use the dedicated command
gui-image-studio-designer

# Create sample images for testing
gui-image-studio-create-samples

# Embed images from a folder
gui-image-studio-generate \
  --folder images/ \
  --output embedded_images.py \
  --quality 85

Advanced Features

Image Transformations

from gui_image_studio import get_image

# Apply transformations
image = get_image(
    "photo.jpg",
    framework="customtkinter",
    size=(200, 200),
    rotate=45,
    tint_color=(255, 0, 0),
    tint_intensity=0.3,
    contrast=1.2,
    saturation=1.5,
    grayscale=False,
    transparency=1.0
)

Animated GIFs

from gui_image_studio import get_image

# Load animated GIF
animation_data = get_image(
    "animation.gif",
    framework="customtkinter",
    size=(100, 100),
    animated=True,
    frame_delay=100
)

# Use the frames in your application
frames = animation_data["animated_frames"]
delay = animation_data["frame_delay"]

Supported Frameworks

• tkinter: Python's standard GUI library
• customtkinter: Modern tkinter-based framework

Examples

Check out the examples/ directory for comprehensive usage examples:

• 01_basic_usage.py - Basic image loading and display
• 02_theming_examples.py - Theme integration examples
• 03_image_transformations.py - Image manipulation features
• 04_animated_gifs.py - Animated GIF handling
• 05_advanced_features.py - Advanced usage patterns
• 06_image_designer_gui.py - Launch the Image Studio GUI
• 07_using_designed_images.py - Use images created with the designer

Run all examples:

python examples/run_examples.py

API Reference

Core Functions

get_image(image_name, framework="tkinter", **kwargs)

Load and return an image object for the specified GUI framework.

Parameters:

• image_name (str): Name of the embedded image (e.g., 'icon.png')
• framework (str): GUI framework ("tkinter" or "customtkinter")
• size (tuple): Resize image to (width, height), default (32, 32)
• theme (str): Theme name ("default", "dark", "light"), default "default"
• rotate (int): Rotate image by degrees, default 0
• grayscale (bool): Convert to grayscale, default False
• tint_color (tuple): Apply color tint as (R, G, B), default None
• tint_intensity (float): Tint blending factor (0.0-1.0), default 0.0
• contrast (float): Adjust contrast (1.0 = normal), default 1.0
• saturation (float): Adjust saturation (1.0 = normal), default 1.0
• transparency (float): Adjust transparency (0.0-1.0), default 1.0
• animated (bool): Process animated GIFs, default False
• frame_delay (int): Animation frame delay in ms, default 100
• format_override (str): Convert to format ("PNG", "JPEG", etc.), default None

embed_images_from_folder(folder_path, output_file="embedded_images.py", compression_quality=85)

Process all images in a folder and generate an embedded Python module.

Parameters:

• folder_path (str): Path to folder containing images
• output_file (str): Output Python file path, default "embedded_images.py"
• compression_quality (int): JPEG/WebP compression quality (1-100), default 85

Supported Formats:

• PNG, JPG, JPEG, BMP, TIFF, GIF, WebP, ICO

Sample Creation

create_sample_images(output_dir="sample_images")

Generate sample images for testing purposes.

Development

Setting up Development Environment

git clone https://github.com/stntg/gui-image-studio.git
cd gui-image-studio
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Running Tests

python test_package.py

Project Structure

gui-image-studio/
├── src/gui_image_studio/     # Main package
│   ├── __init__.py           # Package initialization
│   ├── __main__.py           # Module entry point
│   ├── cli.py                # Command line interface
│   ├── generator.py          # Image embedding generator
│   ├── image_loader.py       # Image loading utilities
│   ├── image_studio.py       # GUI Image Studio application
│   ├── sample_creator.py     # Sample image creation
│   └── embedded_images.py    # Default embedded images
├── examples/                 # Usage examples
├── tests/                    # Test files
├── docs/                     # Documentation
├── README.md                 # This file
├── LICENSE                   # License file
├── pyproject.toml            # Modern Python packaging
├── setup.py                  # Legacy packaging support
└── launch_designer.py        # GUI launcher script

Requirements

• Python 3.8+
• Pillow (PIL) >= 8.0.0
• tkinter (usually included with Python)
• customtkinter >= 5.0.0 (optional, for customtkinter support)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

Version 1.0.0

• Initial release
• Basic image embedding functionality
• Support for tkinter and customtkinter
• Image transformation features
• Command line interface
• Comprehensive examples

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Acknowledgments

• Built with Pillow for image processing
• Supports customtkinter for modern GUI development
• Inspired by the need for easy image embedding in Python GUI applications