First Steps

Welcome to GUI Image Studio! This guide will help you get started with the basics of using GUI Image Studio for image processing and GUI development.

Quick Start Checklist

Before we begin, make sure you have:

✅ Installed GUI Image Studio (see Installation Guide) ✅ Python 3.8+ installed ✅ Basic Python knowledge ✅ A few test images (or use our sample creator)

Your First Image

Let’s start with the most basic operation - loading and displaying an image.

Step 1: Create Sample Images

First, let’s create some sample images to work with:

gui-image-studio-create-samples

This creates a sample_images/ folder with various test images.

Step 2: Load Your First Image

from gui_image_studio import get_image
import tkinter as tk

# Create a simple window
root = tk.Tk()
root.title("My First GUI Image Studio App")

# Load an image
image = get_image(
    "sample_icon",  # Use built-in sample
    framework="tkinter",
    size=(64, 64)
)

# Display it
label = tk.Label(root, image=image)
label.pack(pady=20)

# Keep reference to prevent garbage collection
label.image = image

root.mainloop()

Step 3: Run Your First App

Save the code above as first_app.py and run:

python first_app.py

Congratulations! You’ve created your first GUI Image Studio application.

Understanding the Basics

Core Concepts

1. Framework Support

GUI Image Studio supports two main GUI frameworks:

# For standard tkinter
image = get_image("my_image.png", framework="tkinter")

# For modern customtkinter
image = get_image("my_image.png", framework="customtkinter")

2. Image Sources

You can load images from various sources:

# Built-in samples
image = get_image("sample_icon", framework="tkinter")

# Local files
image = get_image("path/to/image.png", framework="tkinter")

# From embedded resources (after using embed_images_from_folder)
image = get_image("my_embedded_image", framework="tkinter")

3. Image Transformations

Apply transformations during loading:

image = get_image(
    "sample_photo",
    framework="tkinter",
    size=(200, 150),           # Resize
    rotate=45,                 # Rotate 45 degrees
    tint_color=(255, 0, 0),   # Red tint
    tint_intensity=0.3,        # 30% tint strength
    contrast=1.2,              # Increase contrast
    saturation=1.1,            # Boost saturation
    grayscale=False            # Keep in color
)

Working with Different Frameworks

Tkinter Example

import tkinter as tk
from gui_image_studio import get_image

class ImageApp:
    def __init__(self, root):
        self.root = root
        self.root.title("Tkinter Image App")

        # Load and display image
        self.image = get_image(
            "sample_icon",
            framework="tkinter",
            size=(100, 100)
        )

        self.label = tk.Label(root, image=self.image)
        self.label.pack(pady=20)

        # Add a button to change image
        self.button = tk.Button(
            root,
            text="Change Color",
            command=self.change_color
        )
        self.button.pack()

    def change_color(self):
        # Load same image with different tint
        self.image = get_image(
            "sample_icon",
            framework="tkinter",
            size=(100, 100),
            tint_color=(0, 255, 0),  # Green tint
            tint_intensity=0.5
        )
        self.label.configure(image=self.image)

if __name__ == "__main__":
    root = tk.Tk()
    app = ImageApp(root)
    root.mainloop()

CustomTkinter Example

import customtkinter as ctk
from gui_image_studio import get_image

class ModernImageApp:
    def __init__(self, root):
        self.root = root
        self.root.title("Modern Image App")

        # Set appearance mode
        ctk.set_appearance_mode("dark")

        # Load image for customtkinter
        self.image = get_image(
            "sample_icon",
            framework="customtkinter",
            size=(100, 100),
            theme="dark"  # Use dark theme
        )

        # Create CTkLabel with image
        self.label = ctk.CTkLabel(
            root,
            image=self.image,
            text=""  # No text, just image
        )
        self.label.pack(pady=20)

        # Add modern button
        self.button = ctk.CTkButton(
            root,
            text="Apply Effect",
            command=self.apply_effect
        )
        self.button.pack(pady=10)

    def apply_effect(self):
        # Apply a cool effect
        self.image = get_image(
            "sample_icon",
            framework="customtkinter",
            size=(100, 100),
            theme="dark",
            rotate=15,
            tint_color=(100, 200, 255),  # Cool blue
            tint_intensity=0.4,
            contrast=1.3
        )
        self.label.configure(image=self.image)

if __name__ == "__main__":
    root = ctk.CTk()
    app = ModernImageApp(root)
    root.mainloop()

Creating Your Image Library

Embedding Images from Folders

For distribution, you’ll want to embed images directly in your Python code:

Step 1: Organize Your Images

my_project/
├── images/
│   ├── icons/
│   │   ├── home.png
│   │   ├── save.png
│   │   └── open.png
│   └── backgrounds/
│       ├── main_bg.jpg
│       └── splash.png
└── src/
    └── my_app.py

Step 2: Generate Embedded Images

# Generate from icons folder
gui-image-studio-generate \
  --folder images/icons \
  --output src/icons.py \
  --quality 95

# Generate from backgrounds folder
gui-image-studio-generate \
  --folder images/backgrounds \
  --output src/backgrounds.py \
  --quality 80

Step 3: Use Embedded Images

# Import your embedded images
import sys
sys.path.append('src')

from gui_image_studio import get_image
import tkinter as tk

# Now you can use embedded images by name
root = tk.Tk()

# Use embedded icons (filename without extension)
home_icon = get_image("home", framework="tkinter", size=(32, 32))
save_icon = get_image("save", framework="tkinter", size=(32, 32))

# Create buttons with icons
home_btn = tk.Button(root, image=home_icon, text="Home", compound=tk.LEFT)
save_btn = tk.Button(root, image=save_icon, text="Save", compound=tk.LEFT)

home_btn.pack(pady=5)
save_btn.pack(pady=5)

root.mainloop()

Working with Animated GIFs

GUI Image Studio supports animated GIF processing:

from gui_image_studio import get_image
import tkinter as tk

class AnimatedApp:
    def __init__(self, root):
        self.root = root
        self.root.title("Animated GIF Example")

        # Load animated GIF
        self.animation_data = get_image(
            "sample_animation.gif",  # You'll need an animated GIF
            framework="tkinter",
            size=(200, 200),
            animated=True,
            frame_delay=100
        )

        # Extract frames and delay
        self.frames = self.animation_data["animated_frames"]
        self.delay = self.animation_data["frame_delay"]
        self.current_frame = 0

        # Create label for animation
        self.label = tk.Label(root)
        self.label.pack(pady=20)

        # Start animation
        self.animate()

    def animate(self):
        # Display current frame
        self.label.configure(image=self.frames[self.current_frame])

        # Move to next frame
        self.current_frame = (self.current_frame + 1) % len(self.frames)

        # Schedule next frame
        self.root.after(self.delay, self.animate)

if __name__ == "__main__":
    root = tk.Tk()
    app = AnimatedApp(root)
    root.mainloop()

Using the Visual Designer

GUI Image Studio includes a visual designer for creating and editing images:

Launch the Designer

gui-image-studio-designer

Designer Features:

• Drawing Tools: Brush, pencil, eraser, shapes

• Image Transformations: Resize, rotate, flip, filters

• Multiple Images: Work with several images at once

• Real-time Preview: See changes instantly

• Code Generation: Generate Python code for your images

• Export Options: Save in various formats

Basic Designer Workflow:

1. Create New Image or Open Existing

2. Use Drawing Tools to create/edit

3. Apply Transformations as needed

4. Preview Results in real-time

5. Generate Code for use in your applications

6. Export final images

Common Patterns

Icon Management

from gui_image_studio import get_image
import tkinter as tk

class IconManager:
    def __init__(self, framework="tkinter", size=(24, 24)):
        self.framework = framework
        self.size = size
        self.cache = {}

    def get_icon(self, name, **kwargs):
        # Create cache key
        key = f"{name}_{kwargs}"

        if key not in self.cache:
            self.cache[key] = get_image(
                name,
                framework=self.framework,
                size=self.size,
                **kwargs
            )

        return self.cache[key]

# Usage
icons = IconManager(size=(32, 32))

root = tk.Tk()

# Get icons with caching
home_icon = icons.get_icon("home")
save_icon = icons.get_icon("save", tint_color=(0, 255, 0))

tk.Button(root, image=home_icon).pack()
tk.Button(root, image=save_icon).pack()

root.mainloop()

Theme-Aware Images

from gui_image_studio import get_image
import customtkinter as ctk

class ThemedApp:
    def __init__(self):
        self.root = ctk.CTk()
        self.current_theme = "dark"

        self.setup_ui()
        self.update_theme()

    def setup_ui(self):
        # Theme toggle button
        self.theme_btn = ctk.CTkButton(
            self.root,
            text="Toggle Theme",
            command=self.toggle_theme
        )
        self.theme_btn.pack(pady=10)

        # Image label
        self.image_label = ctk.CTkLabel(self.root, text="")
        self.image_label.pack(pady=20)

    def toggle_theme(self):
        # Switch theme
        self.current_theme = "light" if self.current_theme == "dark" else "dark"
        ctk.set_appearance_mode(self.current_theme)
        self.update_theme()

    def update_theme(self):
        # Load theme-appropriate image
        image = get_image(
            "sample_icon",
            framework="customtkinter",
            size=(100, 100),
            theme=self.current_theme
        )
        self.image_label.configure(image=image)

if __name__ == "__main__":
    app = ThemedApp()
    app.root.mainloop()

Best Practices

Performance Tips

1. Cache Images: Don’t reload the same image repeatedly

2. Appropriate Sizes: Don’t load huge images for small displays

3. Use Compression: Set appropriate quality levels for embedded images

4. Lazy Loading: Load images only when needed

# Good: Cache frequently used images
class ImageCache:
    def __init__(self):
        self._cache = {}

    def get_image(self, name, **kwargs):
        key = f"{name}_{hash(str(kwargs))}"
        if key not in self._cache:
            self._cache[key] = get_image(name, **kwargs)
        return self._cache[key]

# Usage
cache = ImageCache()
image = cache.get_image("icon", framework="tkinter", size=(32, 32))

Error Handling

from gui_image_studio import get_image
import tkinter as tk

def safe_load_image(name, **kwargs):
    try:
        return get_image(name, **kwargs)
    except FileNotFoundError:
        print(f"Image '{name}' not found, using placeholder")
        # Return a placeholder or default image
        return get_image("sample_icon", **kwargs)
    except Exception as e:
        print(f"Error loading image '{name}': {e}")
        return None

# Usage
image = safe_load_image("might_not_exist.png", framework="tkinter")
if image:
    label = tk.Label(root, image=image)
    label.pack()

Code Organization

# Good: Organize image resources
class AppResources:
    def __init__(self, framework="tkinter"):
        self.framework = framework

        # Define all your images in one place
        self.icons = {
            'home': self._load_icon('home'),
            'save': self._load_icon('save'),
            'open': self._load_icon('open'),
        }

        self.backgrounds = {
            'main': self._load_bg('main_background'),
            'splash': self._load_bg('splash_screen'),
        }

    def _load_icon(self, name):
        return get_image(
            name,
            framework=self.framework,
            size=(24, 24)
        )

    def _load_bg(self, name):
        return get_image(
            name,
            framework=self.framework,
            size=(800, 600)
        )

# Usage
resources = AppResources("customtkinter")
home_icon = resources.icons['home']

Next Steps

Now that you understand the basics:

1. Explore the Interface: Interface Overview

2. Learn Image Processing: Image Processing

3. Try Advanced Features: Examples

4. Read API Documentation: API Reference

Common Next Actions

For GUI Developers: - Learn about theme integration - Explore customtkinter support - Study the icon management patterns

For Image Processing: - Experiment with transformations - Learn about batch processing - Try the visual designer

For Distribution: - Master image embedding - Optimize compression settings - Set up build processes

Troubleshooting

Image Not Displaying: - Check if image file exists - Verify framework parameter matches your GUI - Ensure you keep a reference to prevent garbage collection

Performance Issues: - Reduce image sizes - Use appropriate compression - Implement caching

Import Errors: - Verify installation: pip show gui-image-studio - Check Python version compatibility - Review dependency installation

Getting Help

• Documentation: API Reference

• Examples: Examples

• Issues: https://github.com/stntg/gui-image-studio/issues

• Discussions: GitHub Discussions

Remember: Start simple, experiment often, and build up complexity gradually!