Background Picker

A fast, efficient Rust GUI application for scanning directories and selecting desktop backgrounds from image thumbnails. Features intelligent caching and seamless integration with file manager thumbnails.

Features

🖼️ Smart Image Management

• Recursively scans directories for image files
• Displays images as thumbnails in collapsible folder hierarchy
• Supports common formats: JPG, JPEG, PNG, GIF, BMP, WebP
• Configurable thumbnail sizes

⚡ Performance & Caching

• Intelligent thumbnail caching using freedesktop.org standard
• Shares cache with pcmanfm, nautilus, and other file managers
• Parallel thumbnail generation for maximum speed
• Instant loading for previously cached images
• Progressive loading with visual feedback

🚀 Flexible Operation Modes

• GUI Mode (default): Interactive thumbnail browser
• Pregenerate Mode (--pregenerate): Batch cache generation and exit
• Debug Mode (--debug): Detailed operation logging

🎛️ Configurable

• Customizable background setting command (defaults to feh --bg-max)
• Persistent state saving (window size, last selection)
• All settings configurable via command line

Installation

# Clone and build
git clone <repository-url>
cd BackgroundPicker
cargo build --release

# Or run directly
cargo run -- --help

Usage

Interactive Mode (Default)

# Browse current directory
cargo run

# Browse specific directory with custom settings
cargo run -- -d ~/Pictures -t 200 -c "nitrogen --set-scaled"

# Built binary
./target/release/background-picker -d ~/Pictures

Batch Cache Generation

# Pre-generate thumbnails for faster browsing later
cargo run -- --pregenerate -d ~/Pictures

# With detailed progress output
cargo run -- --pregenerate --debug -d ~/Pictures

Two-Step Workflow (Recommended for Large Collections)

# Step 1: Generate all thumbnails (runs in background)
background-picker --pregenerate -d ~/Pictures

# Step 2: Browse with instant thumbnails
background-picker -d ~/Pictures

Command Line Options

Background Setting Commands

The application supports any command-line wallpaper tool:

# feh (default - maintains aspect ratio)
-c "feh --bg-max"

# feh (fills screen, may crop)
-c "feh --bg-scale"

# nitrogen
-c "nitrogen --set-scaled"

# Custom script
-c "/path/to/set-wallpaper.sh"

User Interface

• Click thumbnail: Set as desktop background and exit application
• Expand folders: Click folder names to show/hide thumbnails
• Hover tooltips: See full file paths
• Progress indicators: Visual feedback during thumbnail loading
• Responsive design: Handles collections of any size

Performance Features

Thumbnail Caching

• Uses standard ~/.cache/thumbnails/ directory
• Compatible with pcmanfm, nautilus, thunar, and other file managers
• Automatic cache validation (regenerates if file modified)
• Supports both normal (128x128) and large (256x256) thumbnail sizes

Parallel Processing

• Multi-threaded thumbnail generation using Rayon
• Efficient batch processing for large collections
• Non-blocking UI updates
• Smart memory management

Cache Integration

# Browse images in file manager first (creates thumbnails)
pcmanfm ~/Pictures

# Then use background picker (instant thumbnails!)
background-picker -d ~/Pictures

Dependencies

Built with modern Rust ecosystem:

• egui/eframe - Immediate mode GUI framework
• image - Fast image processing and format support
• rayon - Data parallelism for thumbnail generation
• clap - Command line argument parsing
• serde/serde_yaml - Configuration and state persistence
• walkdir - Efficient directory traversal
• dirs - Cross-platform directory locations
• sha1 - Thumbnail cache key generation

Requirements

• Rust toolchain (2021 edition)
• Wallpaper utility: feh, nitrogen, or custom command
• Linux/Unix environment (uses freedesktop.org standards)

Examples

Basic Usage

# Quick browse and select
background-picker

# Browse specific folder
background-picker -d ~/Wallpapers

Large Collections

# Pre-generate cache for 1000+ images
background-picker --pregenerate -d ~/Pictures

# Later: instant browsing
background-picker -d ~/Pictures

Custom Workflows

# Use with different wallpaper tools
background-picker -c "nitrogen --set-zoom-fill" -d ~/Backgrounds

# Custom thumbnail size for high-DPI displays
background-picker -t 300 -d ~/Pictures

# Debug thumbnail cache behavior
background-picker --debug -d ~/Pictures

Scripting

#!/bin/bash
# Batch generate thumbnails for multiple directories
for dir in ~/Pictures/*/; do
    echo "Processing $dir..."
    background-picker --pregenerate -d "$dir"
done

The application automatically quits after setting a background, making it perfect for quick wallpaper changes and integration with desktop shortcuts or scripts.