Command Line Interface

The cli module provides command-line interfaces for GUI Image Studio functionality.

Command-line interface for gui_image_studio package.

gui_image_studio.cli.generate_embedded_images()[source]

Console script entry point for generating embedded images.

gui_image_studio.cli.create_sample_images()[source]

Console script entry point for creating sample images.

gui_image_studio.cli.launch_designer()[source]

Console script entry point for launching the image studio GUI.

Overview

GUI Image Studio provides three main command-line tools:

  • gui-image-studio-designer - Launch the main GUI application

  • gui-image-studio-create-samples - Generate sample images for testing

  • gui-image-studio-generate - Create embedded image resources

All commands support --help and --version options.

Main Commands

Designer Application

gui_image_studio.cli.launch_designer()[source]

Console script entry point for launching the image studio GUI.

Launch the main GUI Image Studio application.

Usage:

gui-image-studio-designer [OPTIONS] [FILE]

Options:

  • --version - Show version information

  • --theme THEME - Set initial theme (light/dark)

  • --fullscreen - Start in fullscreen mode

  • --debug - Enable debug mode

  • --config FILE - Use custom configuration file

Examples:

# Launch with default settings
gui-image-studio-designer

# Launch with specific image
gui-image-studio-designer photo.jpg

# Launch with dark theme
gui-image-studio-designer --theme dark

# Launch in fullscreen
gui-image-studio-designer --fullscreen

# Launch with debug output
gui-image-studio-designer --debug

Return Codes:

  • 0 - Success

  • 1 - General error

  • 2 - Invalid arguments

  • 3 - File not found

  • 4 - Permission error

Sample Creator

gui_image_studio.cli.create_sample_images()[source]

Console script entry point for creating sample images.

Generate sample images for testing and development.

Usage:

gui-image-studio-create-samples [OPTIONS]

Options:

  • --output-dir DIR - Output directory (default: ./sample_images)

  • --count N - Number of each sample type to create (default: 1)

  • --size WxH - Image size (default: 256x256)

  • --formats FORMAT - Comma-separated list of formats (default: png,jpg,gif)

  • --animated - Include animated GIF samples

  • --overwrite - Overwrite existing files

  • --verbose - Verbose output

Examples:

# Create default samples
gui-image-studio-create-samples

# Create samples in specific directory
gui-image-studio-create-samples --output-dir test_images

# Create multiple samples of each type
gui-image-studio-create-samples --count 5

# Create large samples
gui-image-studio-create-samples --size 1024x1024

# Create only PNG samples
gui-image-studio-create-samples --formats png

# Include animated samples
gui-image-studio-create-samples --animated

# Verbose output with overwrite
gui-image-studio-create-samples --verbose --overwrite

Generated Samples:

  • sample_icon.png - Small icon for UI testing

  • sample_photo.jpg - Photograph for processing tests

  • sample_gradient.png - Gradient for filter testing

  • sample_transparent.png - Image with transparency

  • sample_animation.gif - Animated GIF (if –animated)

  • sample_large.jpg - Large image for performance testing

Resource Generator

gui_image_studio.cli.generate_embedded_images()[source]

Console script entry point for generating embedded images.

Generate embedded image resources for distribution.

Usage:

gui-image-studio-generate [OPTIONS]

Options:

  • --folder DIR - Input folder containing images (default: ./images)

  • --output FILE - Output Python file (default: embedded_images.py)

  • --module-name NAME - Module name for generated code

  • --format FORMAT - Encoding format (base64/bytes, default: base64)

  • --compress - Compress images before embedding

  • --quality N - JPEG quality for compression (1-100, default: 85)

  • --max-size WxH - Maximum image size (default: no limit)

  • --exclude PATTERN - Exclude files matching pattern

  • --include PATTERN - Include only files matching pattern

Examples:

# Generate from default folder
gui-image-studio-generate

# Generate from specific folder
gui-image-studio-generate --folder assets/icons

# Generate with custom output file
gui-image-studio-generate --output my_images.py

# Generate with compression
gui-image-studio-generate --compress --quality 75

# Generate with size limit
gui-image-studio-generate --max-size 512x512

# Generate excluding thumbnails
gui-image-studio-generate --exclude "*thumb*"

# Generate only PNG files
gui-image-studio-generate --include "*.png"

Generated Code Example:

# embedded_images.py (generated)
"""
Embedded images for GUI Image Studio
Generated on: 2024-06-22 10:30:00
"""

import base64
from io import BytesIO
from PIL import Image

# Image data
IMAGES = {
    'sample_icon': 'iVBORw0KGgoAAAANSUhEUgAAABAAAAAQ...',
    'sample_photo': '/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAA...',
}

def get_image(name: str) -> Image.Image:
    """Get embedded image by name."""
    if name not in IMAGES:
        raise KeyError(f"Image '{name}' not found")

    data = base64.b64decode(IMAGES[name])
    return Image.open(BytesIO(data))

def list_images() -> list:
    """List all available embedded images."""
    return list(IMAGES.keys())

Available Functions

The CLI module provides the following functions that can be used programmatically:

gui_image_studio.cli.generate_embedded_images()[source]

Console script entry point for generating embedded images.

gui_image_studio.cli.create_sample_images()[source]

Console script entry point for creating sample images.

gui_image_studio.cli.launch_designer()[source]

Console script entry point for launching the image studio GUI.

Configuration

CLI Configuration File

CLI tools can use a configuration file to set default options:

Location:

  • Windows: %APPDATA%\gui-image-studio\config.ini

  • macOS: ~/Library/Application Support/gui-image-studio/config.ini

  • Linux: ~/.config/gui-image-studio/config.ini

Format:

[designer]
theme = dark
fullscreen = false
debug = false

[samples]
output_dir = ./sample_images
count = 1
size = 256x256
formats = png,jpg,gif
animated = false

[generator]
folder = ./images
output = embedded_images.py
format = base64
compress = false
quality = 85

Environment Variables:

CLI tools also respect environment variables:

export GUI_IMAGE_STUDIO_THEME=dark
export GUI_IMAGE_STUDIO_DEBUG=1
export GUI_IMAGE_STUDIO_CONFIG=/path/to/config.ini

Advanced Usage

Scripting with CLI Tools

Batch Sample Creation:

#!/bin/bash
# Create samples for different test scenarios

# Small samples for unit tests
gui-image-studio-create-samples --output-dir tests/fixtures --size 32x32 --count 3

# Medium samples for integration tests
gui-image-studio-create-samples --output-dir tests/integration --size 256x256 --animated

# Large samples for performance tests
gui-image-studio-create-samples --output-dir tests/performance --size 2048x2048

Automated Resource Generation:

#!/bin/bash
# Build script for embedding resources

# Compress and embed icons
gui-image-studio-generate --folder assets/icons --output src/icons.py --compress --max-size 64x64

# Embed sample images
gui-image-studio-generate --folder sample_images --output src/samples.py --quality 75

CI/CD Integration:

# GitHub Actions example
- name: Generate embedded resources
  run: |
    gui-image-studio-create-samples --output-dir test_data
    gui-image-studio-generate --folder assets --output src/embedded.py

PowerShell Scripting (Windows):

# PowerShell script for Windows
$ErrorActionPreference = "Stop"

# Create test samples
gui-image-studio-create-samples --output-dir "test_images" --verbose

# Generate resources
gui-image-studio-generate --folder "assets" --output "embedded.py" --compress

Write-Host "Resource generation complete"

Error Handling

Exit Codes:

All CLI tools use standard exit codes:

  • 0 - Success

  • 1 - General error

  • 2 - Invalid command line arguments

  • 3 - File or directory not found

  • 4 - Permission denied

  • 5 - Insufficient disk space

  • 6 - Unsupported image format

  • 7 - Memory error

Error Messages:

CLI tools provide clear error messages:

$ gui-image-studio-designer nonexistent.jpg
Error: File 'nonexistent.jpg' not found
Exit code: 3

$ gui-image-studio-create-samples --size invalid
Error: Invalid size format 'invalid'. Use format: WIDTHxHEIGHT
Exit code: 2

Logging:

Enable detailed logging for troubleshooting:

# Enable verbose output
gui-image-studio-designer --debug --verbose

# Redirect output to file
gui-image-studio-create-samples --verbose > creation.log 2>&1

Integration Examples

Makefile Integration:

# Makefile for project build
.PHONY: samples resources clean

samples:
    gui-image-studio-create-samples --output-dir test_data

resources:
    gui-image-studio-generate --folder assets --output src/embedded.py --compress

clean:
    rm -rf test_data src/embedded.py

Python Script Integration:

import subprocess
import sys

def generate_resources():
    """Generate embedded resources using CLI."""
    try:
        result = subprocess.run([
            'gui-image-studio-generate',
            '--folder', 'assets',
            '--output', 'src/embedded.py',
            '--compress'
        ], check=True, capture_output=True, text=True)

        print("Resources generated successfully")
        return True

    except subprocess.CalledProcessError as e:
        print(f"Error generating resources: {e.stderr}")
        return False

if __name__ == "__main__":
    if not generate_resources():
        sys.exit(1)

Docker Integration:

FROM python:3.9-slim

# Install GUI Image Studio
RUN pip install gui-image-studio

# Copy assets
COPY assets/ /app/assets/

# Generate embedded resources
WORKDIR /app
RUN gui-image-studio-generate --folder assets --output embedded.py

# Your application code
COPY . /app/
CMD ["python", "app.py"]

Performance Considerations

Large Image Handling:

# For large images, use compression and size limits
gui-image-studio-generate --folder large_images --compress --max-size 1024x1024 --quality 70

Memory Usage:

# Monitor memory usage during generation
/usr/bin/time -v gui-image-studio-generate --folder assets

Parallel Processing:

# Process multiple folders in parallel
gui-image-studio-generate --folder icons &
gui-image-studio-generate --folder photos &
wait

Troubleshooting

Common Issues:

  1. Command not found:

    # Ensure GUI Image Studio is installed
pip install gui-image-studio

# Check installation
pip show gui-image-studio

  2. Permission errors:

    # Use --output-dir with write permissions
gui-image-studio-create-samples --output-dir ~/test_images

  3. Memory errors with large images:

    # Use size limits and compression
gui-image-studio-generate --max-size 512x512 --compress

  4. Display issues (Linux):

    # Set display for headless systems
export DISPLAY=:0
gui-image-studio-designer

Debug Mode:

Enable debug mode for detailed troubleshooting:

gui-image-studio-designer --debug
# Shows detailed error messages and stack traces