Instafy

Transform your images into Instagram-ready 1080x1080 format with beautiful blurred backgrounds.

Features

• 🎨 Smart Composition: Creates square images with blurred background (cover mode) and sharp foreground (contain mode)
• 📐 Automatic Centering: Intelligently centers both layers for perfect composition
• 🔧 Customizable: Adjustable blur intensity and output size
• 💧 Watermark Support: Add watermarks to your images with automatic rotation for vertical images
• ⚡ Fast: Built in Rust with parallel processing for optimal performance
• 🚀 Parallel Processing: Processes multiple images simultaneously using all available CPU cores
• 📊 Progress Bar: Real-time visual progress indicator with ETA and throughput
• 📝 Detailed Logging: Comprehensive logging with tracing for debugging and monitoring
• 🎯 Batch Processing: Process entire directories of JPG images at once
• ✨ Colored CLI: Beautiful, colored help menu for better UX

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/instafy.git
cd instafy

# Build release version
cargo build --release

# Binary will be at ./target/release/instafy

Using Cargo

cargo install instafy

Configuration

Instafy supports a configuration file to set default values for all options.

Configuration File Location

Place your configuration at: ~/.config/instafy/config.yml

Creating a Configuration File

# Create the config directory
mkdir -p ~/.config/instafy

# Copy the example config
cp config.example.yml ~/.config/instafy/config.yml

# Edit the config file
nano ~/.config/instafy/config.yml

Configuration Options

# Output directory for processed images
output: "./output"

# Blur intensity (sigma value)
blur: 25.0

# Output image size (width and height)
size: 2048

# Path to watermark image
watermark: "/path/to/logo.png"

# Rotate watermark for vertical images
rotate: true

# Rotation direction: "clockwise" or "counter-clockwise"
rotate_direction: "counter-clockwise"

# Watermark size: percentage ("0.15") or pixels ("200px")
watermark_size: "0.15"
# watermark_size: "200px"

All options are optional. CLI arguments always override configuration file values.

Note: Tilde (~) expansion is supported in path values (e.g., ~/path/to/file.png will be expanded to your home directory).

Configuration Priority

Settings are applied in the following order (later overrides earlier):

1. Built-in defaults (blur: 20.0, size: 1080, output: ./instafied, rotate: false)
2. Configuration file (~/.config/instafy/config.yml)
3. CLI arguments (highest priority)

Example: If your config file sets blur: 25.0 but you run instafy ./photos -b 30.0, the blur value will be 30.0.

Usage

Basic Usage

Process all JPG files in a directory:

instafy /path/to/images

Output will be saved to ./instafied/ by default.

Custom Output Directory

instafy /path/to/images -o /path/to/output

Adjust Blur Intensity

instafy /path/to/images -b 30.0

Higher values = more blur (default: 20.0)

Custom Output Size

instafy /path/to/images -s 2048

Create 2048x2048 images instead of the default 1080x1080.

Combined Options

instafy ./photos -o ./instagram -b 25.0 -s 1080

Watermark Support

Add a watermark to your images:

instafy /path/to/images -w /path/to/watermark.png

The watermark should be a PNG image with a 1:1 aspect ratio for best results.

Default Watermark Location

Instafy automatically looks for a watermark at ~/.config/instafy/watermark.png. If this file exists, it will be used by default:

# Create the config directory
mkdir -p ~/.config/instafy

# Copy your watermark
cp my-watermark.png ~/.config/instafy/watermark.png

# Now just run instafy without -w flag
instafy /path/to/images

Rotate Watermark for Vertical Images

Enable automatic rotation for vertical (portrait) images using the -r flag:

instafy /path/to/images -w watermark.png -r

By default, this rotates the watermark 270° clockwise (90° counter-clockwise) for vertical images. You can change the rotation direction using the --rotate-direction flag:

# Default: counter-clockwise (270° clockwise)
instafy /path/to/images -w watermark.png -r

# Clockwise rotation (90° clockwise)
instafy /path/to/images -w watermark.png -r --rotate-direction clockwise

Custom Watermark Size

Control the watermark size using either percentage or pixels:

# Using percentage (default: 0.15 = 15% of canvas)
instafy /path/to/images -w logo.png --watermark-size 0.2

# Using pixels (exact size)
instafy /path/to/images -w logo.png --watermark-size 200px

Percentage format: A decimal value between 0.0 and 1.0 (e.g., 0.15 = 15% of canvas size) Pixel format: An integer followed by "px" (e.g., 200px = exactly 200 pixels)

The watermark will be resized to a square of the specified size before being applied.

Watermark Examples

# With custom watermark
instafy ./photos -w logo.png -o ./output

# With rotation for vertical images (default: counter-clockwise)
instafy ./photos -w logo.png -r

# With rotation for vertical images (clockwise)
instafy ./photos -w logo.png -r --rotate-direction clockwise

# With custom size (percentage)
instafy ./photos -w logo.png --watermark-size 0.2

# With custom size (pixels)
instafy ./photos -w logo.png --watermark-size 250px

# Using default watermark with rotation
instafy ./photos -r

# Complete example with all options
instafy ./photos -o ./instagram -w logo.png -r --rotate-direction counter-clockwise -b 25.0 -s 1080 --watermark-size 0.15

Logging

Instafy uses the tracing library for comprehensive logging. Control log levels using the RUST_LOG environment variable:

Log Levels

# Default (info level) - shows progress and summary
instafy /path/to/images

# Debug mode - shows detailed processing steps
RUST_LOG=debug instafy /path/to/images

# Trace mode - maximum verbosity
RUST_LOG=trace instafy /path/to/images

# Warnings and errors only
RUST_LOG=warn instafy /path/to/images

What Gets Logged

• Info: File discovery, processing progress, success/failure counts
• Debug: Image dimensions, file paths, processing steps, dimension calculations
• Trace: Every internal operation (blur application, overlays, etc.)
• Warn: No files found, processing failures
• Error: File I/O errors, invalid directories, processing failures

How It Works

Instafy creates Instagram-ready square images using a multi-layer approach:

1. Background Layer (Cover Mode):

   • Scales the image to fill the entire canvas (1080x1080)
   • Applies Gaussian blur for a professional background effect
   • Centers the scaled image

2. Foreground Layer (Contain Mode):

   • Scales the image to fit within the canvas while maintaining aspect ratio
   • Keeps the image sharp and clear
   • Centers the image on top of the blurred background

3. Watermark Layer (Optional):

   • Positions watermark at bottom-right corner with padding
   • Automatically rotates for vertical images (when -r flag is used)
   • Scales to 15% of canvas size while maintaining aspect ratio

This technique ensures your photos look professional and fit perfectly on Instagram's square format without cropping important content.

Command Line Options

Transform images into Instagram-ready 1080x1080 format with blurred backgrounds

Usage: instafy [OPTIONS] <DIRECTORY>

Arguments:
  <DIRECTORY>  Path to directory containing JPG images

Options:
  -o, --output <OUTPUT>                       Output directory for processed images
  -b, --blur <BLUR>                           Blur intensity (sigma value) [default: 20.0]
  -s, --size <SIZE>                           Output image size (width and height) [default: 1080]
  -w, --watermark <WATERMARK>                 Path to watermark PNG image (defaults to ~/.config/instafy/watermark.png)
  -r, --rotate                                Rotate watermark for vertical images
      --rotate-direction <ROTATE_DIRECTION>   Rotation direction: clockwise (90°) or counter-clockwise (270°) [default: counter-clockwise]
      --watermark-size <WATERMARK_SIZE>       Watermark size: percentage (0.15) or pixels (200px) [default: 0.15]
  -h, --help                                  Print help
  -V, --version                               Print version

Development

Prerequisites

• Rust 1.70 or later
• Cargo

Building

cargo build

Running Tests

This project uses cargo-nextest for faster test execution:

# Install nextest (if not already installed)
cargo install cargo-nextest

# Run tests
cargo nextest run

Or use standard cargo test:

cargo test

Project Structure

instafy/
├── src/
│   ├── main.rs          # CLI interface and directory processing
│   └── lib.rs           # Core image processing logic
├── Cargo.toml           # Dependencies and project metadata
└── README.md

Technical Details

Image Processing

• Resize Algorithm: Lanczos3 for high-quality downscaling
• Blur Algorithm: Gaussian blur with configurable sigma
• Color Space: RGBA processing with RGB conversion for JPEG output
• Supported Formats: JPG/JPEG input, JPG output

Architecture

• Test-Driven Development: Comprehensive unit tests for all core functionality
• Error Handling: Using anyhow for ergonomic error propagation
• Logging: Structured logging with tracing and tracing-subscriber
• CLI Framework: clap with derive macros for type-safe argument parsing

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Workflow

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (cargo nextest run)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Rust
• Uses the excellent image crate for image processing
• CLI powered by clap
• Logging with tracing

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Made with ❤️ and Rust