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

The visual designer is launched using the CLI command:

gui-image-studio-designer

Resource Generation

gui_image_studio.embed_images_from_folder(...)

Complete pipeline: process folder and generate embedded code 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
)

Basic Usage Pattern

from gui_image_studio import get_image, embed_images_from_folder, create_sample_images

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

# Create sample images
create_sample_images()

# Generate embedded images from folder
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

from gui_image_studio import get_image

# Load from file
image = get_image("photo.jpg", framework="tkinter")

# Load from embedded resources
image = get_image("sample_icon", framework="customtkinter")

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

Image Transformations

from gui_image_studio import get_image

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

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

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

Batch Processing

from gui_image_studio import embed_images_from_folder, create_sample_images

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

# Create sample images for testing
create_sample_images()

GUI Integration

import tkinter as tk
from gui_image_studio import get_image
import subprocess

# Launch the GUI designer
subprocess.run(["gui-image-studio-designer"])

# Or use images in your own GUI
root = tk.Tk()
image = 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()