Image Loader Module

The image_loader module provides core functionality for loading and transforming images for GUI applications. It supports both tkinter and customtkinter frameworks with advanced image processing capabilities.

class gui_image_studio.image_loader.ImageConfig(image_name, framework='tkinter', size=(32, 32), theme='default', grayscale=False, rotate=0, transparency=1.0, format_override=None, animated=False, frame_delay=100, tint_color=None, tint_intensity=0.0, contrast=1.0, saturation=1.0)[source]

Bases: object

Configuration class for image processing parameters.

Parameters:

image_name (str)
framework (str)
size (Tuple[int, int])
theme (str)
grayscale (bool)
rotate (int)
transparency (float)
format_override (str | None)
animated (bool)
frame_delay (int)
tint_color (Tuple[int, int, int] | None)
tint_intensity (float)
contrast (float)
saturation (float)

image_name: str

framework: str = 'tkinter'

size: Tuple[int, int] = (32, 32)

theme: str = 'default'

grayscale: bool = False

rotate: int = 0

transparency: float = 1.0

format_override: str | None = None

animated: bool = False

frame_delay: int = 100

tint_color: Tuple[int, int, int] | None = None

tint_intensity: float = 0.0

contrast: float = 1.0

saturation: float = 1.0

to_transforms_dict()[source]

Convert configuration to transforms dictionary.

Return type:: dict

gui_image_studio.image_loader.get_image(image_name, framework='tkinter', size=(32, 32), theme='default', grayscale=False, rotate=0, transparency=1.0, format_override=None, animated=False, frame_delay=100, tint_color=None, tint_intensity=0.0, contrast=1.0, saturation=1.0)[source]

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

Parameters:

image_name (str) – Name of the image file (e.g., ‘icon.png’).
framework (str) – “tkinter” or “customtkinter”.
size (tuple) – Desired dimensions; used for resizing. For animated GIFs, each frame is resized.
theme (str) – Theme name (e.g., “dark”, “light”); falls back to “default” if not matched.
grayscale (bool) – Convert image to grayscale.
rotate (int) – Rotate image (or each frame) by the given degrees.
transparency (float) – Adjust brightness/opacity (0.0 to 1.0).
format_override (str) – Convert image to this format on the fly (“PNG”, “JPEG”, etc.).
animated (bool) – If True and image is an animated GIF, process all its frames.
frame_delay (int) – Delay (milliseconds) between frames for animated GIFs.
tint_color (tuple or None) – A tuple (R, G, B) for a tint overlay.
tint_intensity (float) – Blending factor (0.0 to 1.0) for tint; 0 means no tint.
contrast (float) – Contrast adjustment factor (1.0 means no change).
saturation (float) – Saturation adjustment factor (1.0 means no change).

Returns:

A Tkinter PhotoImage or a CustomTkinter CTkImage.

For animated GIFs:

A dictionary with keys “animated_frames” (a list of image objects) and “frame_delay”. Use these frames in an animation loop.

Return type:

For static images

gui_image_studio.image_loader.get_image_from_config(config)[source]

Retrieve an embedded image using an ImageConfig object.

This is a convenience function for when you have complex configurations or want to reuse the same configuration multiple times.

Parameters:: config (ImageConfig) – Complete image processing configuration.
Returns:: Same as get_image() - framework-specific image object or animated frames dictionary.
Return type:: Any

Core Functions

get_image

gui_image_studio.image_loader.get_image(image_name, framework='tkinter', size=(32, 32), theme='default', grayscale=False, rotate=0, transparency=1.0, format_override=None, animated=False, frame_delay=100, tint_color=None, tint_intensity=0.0, contrast=1.0, saturation=1.0)[source]

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

Parameters:

image_name (str) – Name of the image file (e.g., ‘icon.png’).
framework (str) – “tkinter” or “customtkinter”.
size (tuple) – Desired dimensions; used for resizing. For animated GIFs, each frame is resized.
theme (str) – Theme name (e.g., “dark”, “light”); falls back to “default” if not matched.
grayscale (bool) – Convert image to grayscale.
rotate (int) – Rotate image (or each frame) by the given degrees.
transparency (float) – Adjust brightness/opacity (0.0 to 1.0).
format_override (str) – Convert image to this format on the fly (“PNG”, “JPEG”, etc.).
animated (bool) – If True and image is an animated GIF, process all its frames.
frame_delay (int) – Delay (milliseconds) between frames for animated GIFs.
tint_color (tuple or None) – A tuple (R, G, B) for a tint overlay.
tint_intensity (float) – Blending factor (0.0 to 1.0) for tint; 0 means no tint.
contrast (float) – Contrast adjustment factor (1.0 means no change).
saturation (float) – Saturation adjustment factor (1.0 means no change).

Returns:

A Tkinter PhotoImage or a CustomTkinter CTkImage.

For animated GIFs:

A dictionary with keys “animated_frames” (a list of image objects) and “frame_delay”. Use these frames in an animation loop.

Return type:

For static images

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

Parameters:

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

Returns:

Framework-specific image object (PhotoImage for tkinter, CTkImage for customtkinter)

Examples:

from gui_image_studio import get_image

# Basic usage
image = get_image("icon.png", framework="tkinter")

# With transformations
image = get_image(
    "photo.jpg",
    framework="customtkinter",
    size=(200, 200),
    tint_color=(255, 0, 0),
    tint_intensity=0.3,
    rotate=45
)

# Animated GIF
animation = get_image(
    "animation.gif",
    framework="tkinter",
    animated=True,
    frame_delay=100
)

save_image

Save images to files in various formats.

Parameters:

image (PIL.Image.Image): Image to save
output_path (str): Path where to save the image
quality (int, optional): JPEG quality (1-100, default 95)
optimize (bool, optional): Optimize file size (default True)

Examples:

# Save as PNG
save_image(image, "output.png")

# Save as JPEG with specific quality
save_image(image, "output.jpg", quality=85)

# Save optimized GIF
save_image(animated_image, "output.gif", optimize=True)

Image Processing Functions

resize_image

Resize images while maintaining quality.

Parameters:

image (PIL.Image.Image): Source image
size (Tuple[int, int]): Target size (width, height)
resample (int, optional): Resampling algorithm (default LANCZOS)
maintain_aspect (bool, optional): Maintain aspect ratio (default False)

Examples:

# Resize to exact dimensions
resized = resize_image(image, (800, 600))

# Resize maintaining aspect ratio
resized = resize_image(image, (800, 600), maintain_aspect=True)

apply_tint

Apply color tints to images.

Parameters:

image (PIL.Image.Image): Source image
color (str): Tint color (hex string, RGB tuple, or color name)
opacity (float, optional): Tint opacity (0.0-1.0, default 0.3)
blend_mode (str, optional): Blending mode (default “multiply”)

Examples:

# Apply red tint
tinted = apply_tint(image, "#FF0000")

# Apply blue tint with custom opacity
tinted = apply_tint(image, "blue", opacity=0.5)

# Apply tint with overlay blend mode
tinted = apply_tint(image, "#00FF00", blend_mode="overlay")

rotate_image

Rotate images by specified angles.

Parameters:

image (PIL.Image.Image): Source image
angle (float): Rotation angle in degrees
expand (bool, optional): Expand canvas to fit rotated image (default True)
fillcolor (str, optional): Background color for empty areas

Examples:

# Rotate 90 degrees clockwise
rotated = rotate_image(image, 90)

# Rotate 45 degrees with white background
rotated = rotate_image(image, 45, fillcolor="white")

flip_image

Flip images horizontally or vertically.

Parameters:

image (PIL.Image.Image): Source image
horizontal (bool, optional): Flip horizontally (default False)
vertical (bool, optional): Flip vertically (default False)

Examples:

# Flip horizontally
flipped = flip_image(image, horizontal=True)

# Flip vertically
flipped = flip_image(image, vertical=True)

# Flip both ways
flipped = flip_image(image, horizontal=True, vertical=True)

Advanced Functions

apply_filter

Apply various image filters and effects.

Parameters:

image (PIL.Image.Image): Source image
filter_type (str): Filter type (“blur”, “sharpen”, “emboss”, etc.)
intensity (float, optional): Filter intensity (0.0-1.0, default 1.0)

Examples:

# Apply blur filter
blurred = apply_filter(image, "blur", intensity=0.5)

# Apply sharpen filter
sharpened = apply_filter(image, "sharpen")

adjust_brightness

Adjust image brightness and contrast.

Parameters:

image (PIL.Image.Image): Source image
brightness (float, optional): Brightness factor (1.0 = no change)
contrast (float, optional): Contrast factor (1.0 = no change)

Examples:

# Increase brightness
brighter = adjust_brightness(image, brightness=1.2)

# Increase contrast
contrasted = adjust_brightness(image, contrast=1.3)

# Adjust both
adjusted = adjust_brightness(image, brightness=1.1, contrast=1.2)

Utility Functions

get_image_info

Get detailed information about an image.

Parameters:

image (PIL.Image.Image): Image to analyze

Returns:

dict: Dictionary containing image information

Examples:

info = get_image_info(image)
print(f"Size: {info['size']}")
print(f"Format: {info['format']}")
print(f"Mode: {info['mode']}")

is_animated

Check if an image is animated (e.g., animated GIF).

Parameters:

image (PIL.Image.Image): Image to check

Returns:

bool: True if image is animated

Examples:

if is_animated(image):
    print("This is an animated image")
else:
    print("This is a static image")

Constants

Supported Formats

SUPPORTED_INPUT_FORMATS = ['.png', '.jpg', '.jpeg', '.gif', '.bmp', '.tiff', '.webp', '.ico']
SUPPORTED_OUTPUT_FORMATS = ['.png', '.jpg', '.jpeg', '.gif', '.bmp', '.tiff', '.webp']

Default Settings

DEFAULT_QUALITY = 95
DEFAULT_RESAMPLE = Image.LANCZOS
DEFAULT_TINT_OPACITY = 0.3

Color Constants

TRANSPARENT = (0, 0, 0, 0)
WHITE = (255, 255, 255)
BLACK = (0, 0, 0)

Error Handling

The image_loader module provides comprehensive error handling:

Common Exceptions:

FileNotFoundError: Image file not found
PIL.UnidentifiedImageError: Unsupported image format
ValueError: Invalid parameter values
MemoryError: Image too large to process
PermissionError: Insufficient permissions to read/write file

Error Handling Example:

try:
    image = get_image("photo.jpg")
    processed = apply_tint(image, "#FF0000")
    save_image(processed, "output.png")
except FileNotFoundError:
    print("Image file not found")
except PIL.UnidentifiedImageError:
    print("Unsupported image format")
except Exception as e:
    print(f"Unexpected error: {e}")

Performance Notes

Memory Usage:: Large images consume significant memory. Consider resizing before processing multiple operations.
Processing Speed:: Complex filters and transformations may take time with large images. Consider showing progress indicators for long operations.
File I/O:: Loading and saving images involves disk I/O. Cache frequently used images in memory when possible.
Threading:: Most functions are thread-safe for read operations, but be careful with concurrent write operations.