Basic Usage Examples
This section demonstrates the fundamental operations you can perform with GUI Image Studio.
Loading and Saving Images
The most basic operations involve loading images from files and saving them in different formats.
Simple Load and Save
# Example: Basic Image Loading and Saving
# Demonstrates how to load an image from a file and save it in a different format.
import gui_image_studio
def convert_image_format(input_path: str, output_path: str) -> bool:
"""
Convert an image from one format to another.
Args:
input_path: Path to the input image
output_path: Path for the output image
Returns:
True if successful, False otherwise
"""
try:
# Load the image
image = gui_image_studio.get_image(input_path)
# Save in new format
gui_image_studio.save_image(image, output_path)
print(f"Successfully converted {input_path} to {output_path}")
return True
except FileNotFoundError:
print(f"Error: Could not find input file {input_path}")
return False
except Exception as e:
print(f"Error converting image: {e}")
return False
# Example usage
if __name__ == "__main__":
# Convert JPEG to PNG
convert_image_format("sample_images/sample_photo.jpg", "output.png")
# Convert PNG to JPEG
convert_image_format("sample_images/sample_icon.png", "output.jpg")
Loading with Error Handling
# Example: Robust Image Loading with Error Handling
# Shows how to handle various error conditions when loading images.
import gui_image_studio
import os
from typing import Optional
from PIL import Image
def safe_load_image(image_path: str, fallback_color: str = "#CCCCCC") -> Optional[Image.Image]:
"""
Safely load an image with comprehensive error handling.
Args:
image_path: Path to the image file
fallback_color: Color to use if loading fails
Returns:
PIL Image object or None if all attempts fail
"""
# Check if file exists
if not os.path.exists(image_path):
print(f"Warning: File {image_path} does not exist")
return None
# Check file size
file_size = os.path.getsize(image_path)
if file_size > 50 * 1024 * 1024: # 50MB limit
print(f"Warning: File {image_path} is very large ({file_size / 1024 / 1024:.1f}MB)")
try:
# Attempt to load the image
image = gui_image_studio.get_image(image_path)
print(f"Successfully loaded {image_path} ({image.size[0]}x{image.size[1]})")
return image
except gui_image_studio.PIL.UnidentifiedImageError:
print(f"Error: {image_path} is not a valid image file")
return None
except MemoryError:
print(f"Error: Not enough memory to load {image_path}")
return None
except PermissionError:
print(f"Error: Permission denied accessing {image_path}")
return None
except Exception as e:
print(f"Unexpected error loading {image_path}: {e}")
return None
# Example usage
if __name__ == "__main__":
test_files = [
"sample_images/sample_photo.jpg",
"sample_images/sample_icon.png",
"nonexistent_file.jpg",
"sample_images/sample_animation.gif"
]
for file_path in test_files:
image = safe_load_image(file_path)
if image:
print(f" Format: {image.format}, Mode: {image.mode}")
print()
Basic Image Transformations
These examples show how to perform common image transformations.
Resizing Images
# Example: Image Resizing Operations
# Demonstrates different ways to resize images while maintaining quality.
import gui_image_studio
from typing import Tuple
def resize_image_examples():
"""Demonstrate various image resizing techniques."""
# Load a sample image
image = gui_image_studio.get_image("sample_images/sample_photo.jpg")
original_size = image.size
print(f"Original size: {original_size[0]}x{original_size[1]}")
# 1. Resize to exact dimensions
resized_exact = gui_image_studio.resize_image(image, (800, 600))
gui_image_studio.save_image(resized_exact, "resized_exact.jpg")
print("Saved: resized_exact.jpg (800x600)")
# 2. Resize maintaining aspect ratio (fit within bounds)
def resize_maintain_aspect(img, max_size: Tuple[int, int]) -> Tuple[int, int]:
"""Calculate new size maintaining aspect ratio."""
width, height = img.size
max_width, max_height = max_size
# Calculate scaling factor
scale = min(max_width / width, max_height / height)
new_width = int(width * scale)
new_height = int(height * scale)
return (new_width, new_height)
new_size = resize_maintain_aspect(image, (800, 600))
resized_aspect = gui_image_studio.resize_image(image, new_size)
gui_image_studio.save_image(resized_aspect, "resized_aspect.jpg")
print(f"Saved: resized_aspect.jpg ({new_size[0]}x{new_size[1]})")
# 3. Create thumbnail
thumbnail_size = (150, 150)
thumb_size = resize_maintain_aspect(image, thumbnail_size)
thumbnail = gui_image_studio.resize_image(image, thumb_size)
gui_image_studio.save_image(thumbnail, "thumbnail.jpg")
print(f"Saved: thumbnail.jpg ({thumb_size[0]}x{thumb_size[1]})")
# 4. Scale by percentage
scale_factor = 0.5 # 50% of original size
scaled_size = (int(original_size[0] * scale_factor),
int(original_size[1] * scale_factor))
scaled = gui_image_studio.resize_image(image, scaled_size)
gui_image_studio.save_image(scaled, "scaled_50percent.jpg")
print(f"Saved: scaled_50percent.jpg ({scaled_size[0]}x{scaled_size[1]})")
if __name__ == "__main__":
resize_image_examples()
Applying Color Tints
# Example: Color Tinting Operations
# Shows how to apply various color tints and effects to images.
import gui_image_studio
def color_tinting_examples():
"""Demonstrate different color tinting techniques."""
# Load a sample image
image = gui_image_studio.get_image("sample_images/sample_photo.jpg")
# Define color palette
colors = {
"warm_red": "#FF6B6B",
"cool_blue": "#4ECDC4",
"vintage_sepia": "#D2B48C",
"forest_green": "#2ECC71",
"sunset_orange": "#FF8C42",
"royal_purple": "#9B59B6"
}
print("Applying color tints...")
for name, color in colors.items():
# Apply tint
tinted = gui_image_studio.apply_tint(image, color)
# Save with descriptive filename
filename = f"tinted_{name}.jpg"
gui_image_studio.save_image(tinted, filename)
print(f"Saved: {filename} (tint: {color})")
# Create a comparison grid (if you have PIL available)
try:
from PIL import Image
# Load all tinted images
tinted_images = []
for name in colors.keys():
tinted_img = gui_image_studio.get_image(f"tinted_{name}.jpg")
# Resize for grid
tinted_img = gui_image_studio.resize_image(tinted_img, (200, 150))
tinted_images.append(tinted_img)
# Create 2x3 grid
grid_width = 200 * 3
grid_height = 150 * 2
grid = Image.new('RGB', (grid_width, grid_height), 'white')
for i, img in enumerate(tinted_images):
x = (i % 3) * 200
y = (i // 3) * 150
grid.paste(img, (x, y))
gui_image_studio.save_image(grid, "tint_comparison_grid.jpg")
print("Saved: tint_comparison_grid.jpg (comparison grid)")
except ImportError:
print("PIL not available for grid creation")
if __name__ == "__main__":
color_tinting_examples()
Rotating and Flipping Images
# Example: Image Rotation and Flipping
# Demonstrates geometric transformations like rotation and flipping.
import gui_image_studio
def geometric_transformations():
"""Demonstrate rotation and flipping operations."""
# Load a sample image
image = gui_image_studio.get_image("sample_images/sample_icon.png")
print("Applying geometric transformations...")
# Rotation examples
rotation_angles = [90, 180, 270, 45, -45]
for angle in rotation_angles:
rotated = gui_image_studio.rotate_image(image, angle)
filename = f"rotated_{angle}deg.png"
gui_image_studio.save_image(rotated, filename)
print(f"Saved: {filename}")
# Flipping examples
flip_operations = [
("horizontal", True, False),
("vertical", False, True),
("both", True, True)
]
for name, horizontal, vertical in flip_operations:
flipped = gui_image_studio.flip_image(image,
horizontal=horizontal,
vertical=vertical)
filename = f"flipped_{name}.png"
gui_image_studio.save_image(flipped, filename)
print(f"Saved: {filename}")
# Combined transformations
# Rotate and then flip
rotated_flipped = gui_image_studio.rotate_image(image, 45)
rotated_flipped = gui_image_studio.flip_image(rotated_flipped, horizontal=True)
gui_image_studio.save_image(rotated_flipped, "rotated_45_flipped_h.png")
print("Saved: rotated_45_flipped_h.png (combined transformation)")
if __name__ == "__main__":
geometric_transformations()
Working with Different Image Formats
Format Conversion and Optimization
# Example: Image Format Conversion and Optimization
# Shows how to convert between different image formats and optimize file sizes.
import gui_image_studio
import os
def format_conversion_examples():
"""Demonstrate format conversion and optimization."""
# Load a sample image
image = gui_image_studio.get_image("sample_images/sample_photo.jpg")
print("Converting to different formats...")
# Save as PNG (lossless)
gui_image_studio.save_image(image, "converted.png")
png_size = os.path.getsize("converted.png")
print(f"PNG: {png_size / 1024:.1f} KB")
# Save as JPEG with different quality levels
quality_levels = [95, 85, 75, 60, 40]
for quality in quality_levels:
filename = f"converted_q{quality}.jpg"
gui_image_studio.save_image(image, filename, quality=quality)
file_size = os.path.getsize(filename)
print(f"JPEG Q{quality}: {file_size / 1024:.1f} KB")
# Save as WebP (if supported)
try:
gui_image_studio.save_image(image, "converted.webp")
webp_size = os.path.getsize("converted.webp")
print(f"WebP: {webp_size / 1024:.1f} KB")
except Exception as e:
print(f"WebP not supported: {e}")
# Create optimized versions
# Small thumbnail
thumbnail = gui_image_studio.resize_image(image, (150, 150))
gui_image_studio.save_image(thumbnail, "thumbnail_optimized.jpg", quality=80)
thumb_size = os.path.getsize("thumbnail_optimized.jpg")
print(f"Optimized thumbnail: {thumb_size / 1024:.1f} KB")
if __name__ == "__main__":
format_conversion_examples()
Batch Processing Basics
Processing Multiple Images
# Example: Basic Batch Processing
# Shows how to process multiple images with the same operations.
import gui_image_studio
import os
from typing import List
def batch_process_images(input_folder: str, output_folder: str,
operations: List[str] = None):
"""
Process all images in a folder with specified operations.
Args:
input_folder: Folder containing input images
output_folder: Folder for processed images
operations: List of operations to perform
"""
if operations is None:
operations = ["resize", "tint"]
# Create output folder if it doesn't exist
os.makedirs(output_folder, exist_ok=True)
# Supported image extensions
supported_extensions = ('.png', '.jpg', '.jpeg', '.gif', '.bmp')
# Find all image files
image_files = []
for filename in os.listdir(input_folder):
if filename.lower().endswith(supported_extensions):
image_files.append(filename)
print(f"Found {len(image_files)} images to process")
# Process each image
for i, filename in enumerate(image_files, 1):
print(f"Processing {i}/{len(image_files)}: {filename}")
try:
# Load image
input_path = os.path.join(input_folder, filename)
image = gui_image_studio.get_image(input_path)
# Apply operations
processed_image = image
if "resize" in operations:
# Resize to max 800x600 maintaining aspect ratio
width, height = processed_image.size
if width > 800 or height > 600:
scale = min(800 / width, 600 / height)
new_size = (int(width * scale), int(height * scale))
processed_image = gui_image_studio.resize_image(processed_image, new_size)
if "tint" in operations:
# Apply a subtle blue tint
processed_image = gui_image_studio.apply_tint(processed_image, "#4ECDC4")
# Save processed image
name, ext = os.path.splitext(filename)
output_filename = f"{name}_processed{ext}"
output_path = os.path.join(output_folder, output_filename)
gui_image_studio.save_image(processed_image, output_path)
print(f" Saved: {output_filename}")
except Exception as e:
print(f" Error processing {filename}: {e}")
print("Batch processing complete!")
if __name__ == "__main__":
# Process sample images
batch_process_images("sample_images", "processed_images",
operations=["resize", "tint"])
Running the Examples
To run these examples:
Create sample images first:
gui-image-studio-create-samples
Run individual examples:
python basic_load_save.py python resize_examples.py python tinting_examples.py
Check the output files in your current directory
Each example is self-contained and includes error handling to make it robust for real-world use.
Next Steps
After mastering these basic operations, you can:
Explore Image Processing Examples for advanced filtering and effects
Learn about animation_creation for working with animated GIFs
Check out gui_application for building complete image editing applications
Try batch_processing for automating image workflows