Image Studio GUI Module

The image_studio module provides the main GUI application class and related components for the GUI Image Studio application.

Refactored Image Studio package.

class gui_image_studio.image_studio.EnhancedImageDesignerGUI

Bases: object

Main GUI application for image design and code generation.

center_window()

Center the window on the desktop.

Return type:

None

setup_button_styles()

Setup custom button styles for prominent display.

Return type:

None

update_button_styles()

Update button styles based on whether images are present.

setup_ui()

Setup the enhanced user interface with threepanewindows.

Return type:

None

build_left_panel(parent)

Build the left panel with tools and image management.

Return type:

None

build_center_panel(parent)

Build the center panel with the drawing canvas.

Return type:

None

build_right_panel(parent)

Build the right panel with properties and code generation.

Return type:

None

setup_bindings()

Setup keyboard and mouse bindings.

select_tool(tool)

Select a drawing tool.

update_tool_cursor(tool)

Update the canvas cursor based on the selected tool and user settings.

get_cursor_fallback_options(tool)

Get fallback cursor options based on tool, platform, and handedness.

load_cursor_settings()

Load cursor settings from file.

save_cursor_settings()

Save cursor settings to file.

reset_cursor_settings()

Reset cursor settings to defaults.

choose_color()

Open color chooser dialog.

update_ui_state()

Update UI state based on current selection.

update_canvas()

Update the canvas display.

show_canvas_instructions()

Show instructions on empty canvas.

draw_grid(display_size)

Draw grid on the canvas.

on_image_select(event)

Handle image selection from listbox.

select_image(name)

Select an image.

draw_on_image(x, y)

Draw on the current image using the new tool system.

draw_line_on_image(x1, y1, x2, y2)

Draw a line on the current image using the new tool system.

draw_shape(x1, y1, x2, y2)

Draw a shape on the current image using the new tool system.

update_shape_preview(x1, y1, x2, y2)

Update the preview shape on canvas.

clear_preview()

Clear the preview shape from canvas.

update_pixel_highlight(x, y)

Highlight the pixel that will be affected by drawing tools.

clear_pixel_highlight()

Clear the pixel highlight from canvas.

update_preview(event=None)

Update the live preview based on current settings.

setup_preview_bindings()

Set up preview canvas event bindings.

on_drawing_complete()

Called when a drawing operation is completed.

on_image_modified()

Called when an image is modified in any way.

toggle_left_panel()

Toggle left panel visibility.

toggle_right_panel()

Toggle right panel visibility.

reset_panel_layout()

Reset panel layout to default.

preview_code()

Preview the generated embedded code.

generate_code_file()

Generate the embedded code file.

show_quick_start()

Show quick start guide.

show_info_help()

Show image information help.

show_transparency_help()

Show transparency features help.

show_code_help()

Show code generation help.

show_shortcuts()

Show keyboard shortcuts.

show_tips()

Show tips and tricks.

show_troubleshooting()

Show troubleshooting guide.

apply_blur()

Apply blur filter to current image.

apply_sharpen()

Apply sharpen filter to current image.

apply_emboss()

Apply emboss filter to current image.

apply_transparent_background()

Make background transparent.

remove_background()

Remove background from image.

show_image_info()

Show comprehensive image information.

apply_rotation()

Apply rotation to current image.

reset_rotation()

Reset image rotation to 0 degrees.

cleanup_memory()

Clean up memory usage.

check_memory_usage()

Check current memory usage.

update_rotation_display(value=None)

Update rotation display when slider changes.

on_rotation_entry_change(event=None)

Handle rotation entry changes.

preview_buttons()

Preview images as buttons.

preview_icons()

Preview images as icons.

preview_backgrounds()

Preview images as backgrounds.

preview_sprites()

Preview images as game sprites.

preview_ui_elements()

Preview images as UI elements.

preview_general()

Preview images in general format.

new_image()

Create a new blank image.

load_image()

Load an image from file.

export_images()

Export images to a folder.

update_base_image()

Update base image after resize.

clear_canvas()

Clear the canvas.

zoom_in()

Zoom in on the canvas.

zoom_out()

Zoom out on the canvas.

reset_zoom()

Reset zoom to 100%.

fit_to_window()

Fit canvas to window.

toggle_grid()

Toggle grid display.

open_cursor_settings()

Open cursor settings dialog.

show_about()

Show about dialog.

show_help()

Show help window.

start_tutorial()

Start the interactive tutorial.

show_shortcuts_help()

Show keyboard shortcuts help.

show_tools_help()

Show tools reference help.

show_troubleshooting_help()

Show troubleshooting help.

open_online_help()

Open online documentation.

duplicate_image()

Duplicate the selected image.

delete_image()

Delete the selected image.

zoom_fit()

Fit image to canvas.

on_name_change(event)

Handle name change in properties.

rename_image(old_name, new_name)

Rename an image.

resize_image()

Resize the current image.

generate_python_code()

Generate Python code for images.

generate_tkinter_code()

Generate Tkinter code for images.

update_image_list()

Update the image list display.

add_text(x, y)

Add text to the current image.

on_closing()

Handle application closing.

run()

Run the application.

class gui_image_studio.image_studio.ToolTip(widget, text)

Bases: object

Simple tooltip class for widgets.

Parameters:

• widget (Widget)

• text (str)

on_enter(event=None)

Show tooltip on mouse enter.

Parameters:

event (Event | None)

Return type:

None

on_leave(event=None)

Hide tooltip on mouse leave.

Parameters:

event (Event | None)

Return type:

None

Main Application Class

ImageStudio

The main GUI application class that provides a complete image editing interface.

Initialization:

import tkinter as tk
from gui_image_studio import ImageStudio

root = tk.Tk()
app = ImageStudio(root)
app.pack(fill=tk.BOTH, expand=True)
root.mainloop()

Key Features:

• Professional image editing interface

• Real-time preview capabilities

• Undo/redo functionality

• Theme support (light/dark)

• Plugin architecture

• Batch processing tools

• Animation timeline (for GIFs)

Main Components:

• Canvas Area: Central image display and editing area

• Tool Palette: Left sidebar with editing tools

• Properties Panel: Right sidebar with tool settings

• Menu Bar: Standard application menus

• Status Bar: Information and progress display

• Timeline: Animation frame management (when applicable)

Methods:

load_image

Load an image into the editor.

Parameters:

• file_path (str, optional): Path to image file. If None, opens file dialog.

Example:

# Load specific file
app.load_image("photo.jpg")

# Open file dialog
app.load_image()

save_image

Save the current image.

Parameters:

• file_path (str, optional): Path for saving. If None, opens save dialog.

• quality (int, optional): JPEG quality (1-100, default 95)

Example:

# Save to specific file
app.save_image("output.png")

# Open save dialog
app.save_image()

apply_filter

Apply a filter to the current image.

Parameters:

• filter_name (str): Name of the filter to apply

• parameters (dict, optional): Filter-specific parameters

Example:

# Apply blur filter
app.apply_filter("blur", {"radius": 2.0})

# Apply tint
app.apply_filter("tint", {"color": "#FF6B6B", "opacity": 0.3})

undo

Undo the last operation.

Example:

app.undo()

redo

Redo the last undone operation.

Example:

app.redo()

set_theme

Change the application theme.

Parameters:

• theme_name (str): Theme name (“light”, “dark”, or custom theme)

Example:

app.set_theme("dark")

GUI Components

ToolPalette

Left sidebar containing editing tools.

Available Tools:

• Selection Tools: Rectangle, ellipse, lasso, magic wand

• Drawing Tools: Brush, pencil, eraser, fill bucket

• Transform Tools: Move, rotate, scale, crop

• Filter Tools: Quick access to common filters

Usage:

# Access current tool
current_tool = app.tool_palette.current_tool

# Set tool programmatically
app.tool_palette.set_tool("brush")

PropertiesPanel

Right sidebar showing tool properties and image information.

Sections:

• Tool Properties: Settings for the current tool

• Image Information: Size, format, color mode

• History: Recent operations

• Layers: Layer management (if supported)

Usage:

# Get image info
info = app.properties_panel.get_image_info()
print(f"Size: {info['size']}, Format: {info['format']}")

ImageCanvas

Central canvas area for image display and editing.

Features:

• Zoom and pan capabilities

• Real-time editing preview

• Grid and ruler overlays

• Selection visualization

• Multi-layer support

Usage:

# Zoom operations
app.canvas.zoom_in()
app.canvas.zoom_out()
app.canvas.fit_to_window()

# Get canvas state
zoom_level = app.canvas.get_zoom_level()
selection = app.canvas.get_selection()

Timeline

Animation timeline for GIF editing (shown when working with animated images).

Features:

• Frame-by-frame editing

• Timing adjustment

• Onion skinning

• Playback controls

Usage:

# Timeline operations (when animation is loaded)
app.timeline.add_frame()
app.timeline.delete_frame(frame_index)
app.timeline.set_frame_duration(frame_index, 100)  # 100ms

Event System

The ImageStudio class uses an event-driven architecture for communication between components.

Event Types:

• image_loaded: Fired when a new image is loaded

• image_modified: Fired when the image is changed

• tool_changed: Fired when the active tool changes

• selection_changed: Fired when the selection changes

Event Handling:

def on_image_loaded(event_data):
    print(f"Image loaded: {event_data['file_path']}")

# Subscribe to events
app.subscribe("image_loaded", on_image_loaded)

# Fire custom events
app.fire_event("custom_event", {"data": "value"})

Customization

Custom Tools

Create custom tools by extending the base Tool class:

from gui_image_studio.image_studio import Tool

class CustomTool(Tool):
    def __init__(self):
        super().__init__("Custom Tool", "custom_icon.png")

    def on_mouse_down(self, x, y):
        # Handle mouse down event
        pass

    def on_mouse_drag(self, x, y):
        # Handle mouse drag event
        pass

    def on_mouse_up(self, x, y):
        # Handle mouse up event
        pass

# Register the tool
app.tool_palette.register_tool(CustomTool())

Custom Filters

Create custom filters:

from gui_image_studio.image_studio import Filter

class CustomFilter(Filter):
    def __init__(self):
        super().__init__("Custom Filter", "custom_filter")

    def apply(self, image, parameters=None):
        # Apply custom processing
        processed_image = self.process_image(image, parameters)
        return processed_image

# Register the filter
app.register_filter(CustomFilter())

Custom Themes

Create custom themes:

custom_theme = {
    "name": "custom_theme",
    "colors": {
        "bg_primary": "#2B2B2B",
        "bg_secondary": "#3C3C3C",
        "fg_primary": "#FFFFFF",
        "fg_secondary": "#CCCCCC",
        "accent": "#007ACC",
        "border": "#555555"
    },
    "fonts": {
        "default": ("Segoe UI", 9),
        "heading": ("Segoe UI", 12, "bold"),
        "monospace": ("Consolas", 9)
    }
}

app.register_theme(custom_theme)
app.set_theme("custom_theme")

Configuration

Application Settings

Configure the application behavior:

# Set default settings
app.settings.update({
    "auto_save": True,
    "auto_save_interval": 300,  # 5 minutes
    "max_undo_levels": 50,
    "default_quality": 95,
    "show_grid": False,
    "grid_size": 10
})

Keyboard Shortcuts

Customize keyboard shortcuts:

# Default shortcuts
shortcuts = {
    "Ctrl+O": "open_file",
    "Ctrl+S": "save_file",
    "Ctrl+Z": "undo",
    "Ctrl+Y": "redo",
    "Ctrl++": "zoom_in",
    "Ctrl+-": "zoom_out",
    "Ctrl+0": "fit_to_window"
}

app.set_shortcuts(shortcuts)

Performance Considerations

Memory Management

• Large images are automatically tiled for display

• Undo history is limited to prevent memory issues

• Temporary files are cleaned up automatically

Threading

• Long operations run in background threads

• Progress indicators show operation status

• UI remains responsive during processing

Optimization Tips

# Optimize for large images
app.settings["tile_size"] = 512  # Smaller tiles for large images
app.settings["preview_quality"] = "fast"  # Faster preview rendering

# Optimize for performance
app.settings["real_time_preview"] = False  # Disable for complex operations
app.settings["max_image_size"] = (4096, 4096)  # Limit maximum image size

Error Handling

The ImageStudio class provides comprehensive error handling:

Common Exceptions:

• ImageStudioError: Base exception for application errors

• UnsupportedFormatError: Unsupported image format

• InsufficientMemoryError: Not enough memory for operation

• OperationCancelledError: User cancelled operation

Error Handling Example:

try:
    app.load_image("large_image.jpg")
except gui_image_studio.UnsupportedFormatError:
    print("Image format not supported")
except gui_image_studio.InsufficientMemoryError:
    print("Not enough memory to load image")
except Exception as e:
    print(f"Unexpected error: {e}")

Error Recovery:

The application includes automatic error recovery:

• Corrupted files are handled gracefully

• Memory errors trigger cleanup and retry

• UI state is preserved during errors

• Auto-save prevents data loss

Integration Examples

Embedding in Existing Applications

import tkinter as tk
from gui_image_studio import ImageStudio

class MyApplication:
    def __init__(self):
        self.root = tk.Tk()
        self.setup_ui()

    def setup_ui(self):
        # Create main frame
        main_frame = tk.Frame(self.root)
        main_frame.pack(fill=tk.BOTH, expand=True)

        # Add other components
        toolbar = tk.Frame(main_frame)
        toolbar.pack(side=tk.TOP, fill=tk.X)

        # Embed ImageStudio
        self.image_studio = ImageStudio(main_frame)
        self.image_studio.pack(fill=tk.BOTH, expand=True)

        # Connect to events
        self.image_studio.subscribe("image_loaded", self.on_image_loaded)

    def on_image_loaded(self, event_data):
        # Handle image loaded event
        print(f"Image loaded in embedded editor: {event_data['file_path']}")

Plugin Development

from gui_image_studio.image_studio import Plugin

class MyPlugin(Plugin):
    def __init__(self):
        super().__init__("My Plugin", "1.0.0")

    def initialize(self, app):
        # Add menu items
        app.add_menu_item("Plugins", "My Plugin", self.run_plugin)

        # Add toolbar button
        app.add_toolbar_button("My Plugin", "plugin_icon.png", self.run_plugin)

    def run_plugin(self):
        # Plugin functionality
        current_image = self.app.get_current_image()
        if current_image:
            processed = self.process_image(current_image)
            self.app.set_current_image(processed)

# Register plugin
app.register_plugin(MyPlugin())