API Reference

Complete API documentation for all GUI Image Studio classes and functions.

API Modules:

Overview

The GUI Image Studio API is organized into several modules:

Core Image Processing

gui_image_studio.get_image(image_name[, ...])

Retrieve an embedded image with dynamic transformations and optional animated GIF support.

GUI Application

gui_image_studio.launch_designer()

Launch the GUI Image Studio.

Resource Generation

gui_image_studio.embed_images_from_folder(...)

Processes all valid images in a folder, applies optional JPEG/WebP compression, categorizes them by theme (if the filename starts with a theme followed by an underscore), and writes them into an output Python file.

Sample Creation

gui_image_studio.create_sample_images()

Create a variety of sample images for testing gui_image_studio functionality.

Command Line Interface

gui_image_studio.cli.generate_embedded_images()

Console script entry point for generating embedded images.

gui_image_studio.cli.create_sample_images()

Console script entry point for creating sample images.

gui_image_studio.cli.launch_designer()

Console script entry point for launching the image studio GUI.

Quick Reference

Most Common Functions

For most applications, you’ll primarily use these functions:

from gui_image_studio import (
    get_image,                    # Load images from files or resources
    embed_images_from_folder,     # Generate embedded images
    create_sample_images,         # Create sample images
    launch_designer,              # Launch GUI designer
)

Basic Usage Pattern

import gui_image_studio

# Load an image with transformations
image = gui_image_studio.get_image(
    "path/to/image.png",
    framework="tkinter",
    size=(800, 600),
    tint_color=(255, 107, 107),
    tint_intensity=0.3
)

# Create sample images
gui_image_studio.create_sample_images()

# Generate embedded images from folder
gui_image_studio.embed_images_from_folder("images/", "embedded.py")

Common Parameters

Most functions accept these common parameters:

  • image - PIL Image object or path to image file

  • size - Tuple of (width, height) for dimensions

  • color - Color specification (hex string, RGB tuple, or color name)

  • output_path - Path where to save the processed image

  • quality - JPEG quality (1-100, default 95)

Image Format Support

Supported Input Formats:

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

Supported Output Formats:

PNG, JPEG, GIF, BMP, TIFF, WebP

Animation Support:

GIF (with frame timing and optimization)

Error Handling

All functions raise appropriate exceptions for invalid parameters:

  • FileNotFoundError - Image file not found

  • ValueError - Invalid parameter values

  • TypeError - Wrong parameter types

  • PIL.UnidentifiedImageError - Unsupported image format

  • MemoryError - Image too large to process

Type Hints

All public APIs include comprehensive type hints for better IDE support and static analysis:

from typing import Tuple, Union, Optional
from PIL import Image

def resize_image(
    image: Union[Image.Image, str],
    size: Tuple[int, int],
    resample: int = Image.LANCZOS
) -> Image.Image:
    """Resize an image to the specified dimensions."""

Configuration

Global configuration options:

import gui_image_studio

# Set default image quality
gui_image_studio.set_default_quality(90)

# Set default theme
gui_image_studio.set_theme("dark")

# Enable/disable verbose logging
gui_image_studio.set_verbose(True)

Performance Considerations

Memory Usage:

Large images consume significant memory. Consider resizing before processing.

Processing Speed:

Complex operations may take time with large images. Use progress callbacks when available.

File I/O:

Loading and saving images involves disk I/O. Cache frequently used images in memory.

Threading:

GUI operations must run on the main thread. Use worker threads for heavy processing.

Examples by Category

Basic Image Loading

# Load from file
image = gui_image_studio.get_image("photo.jpg")

# Load from embedded resources
image = gui_image_studio.get_image("sample_icon")

# Load with error handling
try:
    image = gui_image_studio.get_image("might_not_exist.png")
except FileNotFoundError:
    print("Image not found")

Image Transformations

# Load image with transformations applied
resized = gui_image_studio.get_image(
    "image.png",
    size=(800, 600)
)

# Apply color effects
tinted = gui_image_studio.get_image(
    "image.png",
    tint_color=(255, 107, 107),
    tint_intensity=0.3
)

# Geometric transformations
rotated = gui_image_studio.get_image(
    "image.png",
    rotate=45
)

Batch Processing

# Generate embedded images from a folder
gui_image_studio.embed_images_from_folder(
    "input_images/",
    "embedded_images.py",
    compression_quality=85
)

# Create sample images for testing
gui_image_studio.create_sample_images()

GUI Integration

import tkinter as tk
import gui_image_studio

# Launch the GUI designer
gui_image_studio.launch_designer()

# Or use images in your own GUI
root = tk.Tk()
image = gui_image_studio.get_image(
    "icon.png",
    framework="tkinter",
    size=(64, 64)
)
label = tk.Label(root, image=image)
label.pack()
root.mainloop()

Migration Guide

From Version 0.x to 1.0

  • Function names have been standardized

  • Error handling has been improved

  • Type hints have been added throughout

  • Some deprecated functions have been removed

Key Changes

  • Simplified API with focus on get_image() function

  • All image transformations now handled through get_image() parameters

  • Embedded image generation through embed_images_from_folder()

  • GUI designer accessible via launch_designer()