image-collage

Create beautiful 2x2 image collages with a blazing-fast Rust CLI and TUI

At a Glance

# Just run it - opens interactive file browser
$ image-collage

# Or provide 4 images directly
$ image-collage img1.jpg img2.jpg img3.jpg img4.jpg

# That's it! Your collage.jpg is ready

Features

• Blazing Fast - Built in Rust for maximum performance
• Smart Cropping - Automatically center-crops images to perfect squares
• Two Modes - CLI for automation, TUI for interactive selection
• Vim Controls - Navigate with familiar j/k/h/l keys in TUI mode
• Format Support - JPEG, PNG, GIF, BMP, WebP, TIFF input formats
• Cross-Platform - Works on Linux, macOS, and Windows
• Standalone - Single binary, no dependencies required

Screenshots

TUI Mode (Interactive File Browser)

┌─────────────────────────────────────────────────────────────────┐
│            Image Collage - Select 4 Images (3/4)                │
├─────────────────────────────────────────────────────────────────┤
│ /home/user/Pictures/vacation                                    │
├─────────────────────────────────────────────────────────────────┤
│ 📁 ../                                                          │
│ 📁 thumbnails/                                                  │
│ ✓ sunset_beach.jpg                                              │
│ ✓ mountain_view.png                                             │
│   forest_trail.jpg                                              │
│ > city_lights.jpg                                               │ ← Current selection
│ ✓ lake_reflection.jpg                                           │
│   waterfall.gif                                                 │
│   panorama.tiff                                                 │
├─────────────────────────────────────────────────────────────────┤
│ j/k: navigate  l/Enter: select  h: up dir  c: create  q: quit   │
│ Selected: sunset_.jpg, mountain_view.png, lake_reflection.jpg   │
└─────────────────────────────────────────────────────────────────┘

Visual Examples

With Thin Border (default: 2px)

┌───────────┬───────────┐
│           │           │
│  Image 1  │  Image 2  │
│           │           │
├───────────┼───────────┤
│           │           │
│  Image 3  │  Image 4  │
│           │           │
└───────────┴───────────┘

With Thick Border (--border 20)

┌─────────────────────────┐
│ ┌───────┐   ┌───────┐   │
│ │       │   │       │   │
│ │ Img 1 │   │ Img 2 │   │
│ │       │   │       │   │
│ └───────┘   └───────┘   │
│                         │
│ ┌───────┐   ┌───────┐   │
│ │       │   │       │   │
│ │ Img 3 │   │ Img 4 │   │
│ │       │   │       │   │
│ └───────┘   └───────┘   │
└─────────────────────────┘

What It Does

Transforms four images into a perfectly aligned 2x2 grid collage:

Input: 4 images           Output: 1 collage
┌───┐ ┌───┐              ┌────────────
│ 1 │ │ 2 │              │  1  │  2  │
└───┘ └───┘     ──→      ├─────┼─────┤
┌───┐ ┌───┐              │  3  │  4  │
│ 3 │ │ 4 │              └────────────
└───┘ └───┘

CLI Output Example

$ image-collage beach.jpg mountain.jpg forest.jpg city.jpg
Loading images...
Creating collage...
Saving to collage.jpg...
✓ Collage created successfully!

Quick Start

Install

Download the latest binary for your platform from Releases.

# macOS/Linux
chmod +x image-collage
sudo mv image-collage /usr/local/bin/

# Or install with Cargo
cargo install image-collage

Basic Usage

# CLI mode - provide 4 images
image-collage photo1.jpg photo2.jpg photo3.jpg photo4.jpg

# TUI mode - interactive file browser
image-collage

# Custom settings
image-collage img1.jpg img2.jpg img3.jpg img4.jpg \
  --output my-collage.png \
  --size 600 \
  --border 5

TUI Controls

Selected images are marked with ✓

Options

Examples

Different Border Widths

# No border
image-collage *.jpg --border 0

# Thin border (default)
image-collage *.jpg --border 2

# Thick border
image-collage *.jpg --border 20

Different Sizes

# Small (200x200 per image = 402x402 total)
image-collage *.jpg --size 200

# Large (800x800 per image = 1602x1602 total)
image-collage *.jpg --size 800

Different Formats

# Output as PNG
image-collage *.jpg --output collage.png

# Output as JPEG with custom quality
image-collage *.jpg --output collage.jpg --quality 100

Build from Source

git clone https://github.com/guitaripod/image-collage
cd image-collage
cargo build --release
./target/release/image-collage

Workflow

Using TUI Mode

1. Run: image-collage
2. Navigate with j/k keys
3. Select 4 images with Enter
4. Press 'c' to create
5. Done! ✓

Using CLI Mode

1. Run: image-collage *.jpg
2. Done! ✓

Use Cases

• Social Media - Create Instagram-ready photo grids
• Portfolio - Showcase multiple works in one image
• Comparison - Before/after or side-by-side comparisons
• Documentation - Combine multiple screenshots
• Photo Albums - Quick collages for sharing memories

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests

Acknowledgments

Built with:

• image - Image processing
• ratatui - Terminal UI
• clap - CLI parsing