# 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
```bash
# 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
```bash
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
```bash
# 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
```yaml
# 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:
```bash
instafy /path/to/images
```
Output will be saved to `./instafied/` by default.
### Custom Output Directory
```bash
instafy /path/to/images -o /path/to/output
```
### Adjust Blur Intensity
```bash
instafy /path/to/images -b 30.0
```
Higher values = more blur (default: 20.0)
### Custom Output Size
```bash
instafy /path/to/images -s 2048
```
Create 2048x2048 images instead of the default 1080x1080.
### Combined Options
```bash
instafy ./photos -o ./instagram -b 25.0 -s 1080
```
### Watermark Support
Add a watermark to your images:
```bash
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:
```bash
# 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:
```bash
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:
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
cargo build
```
### Running Tests
This project uses `cargo-nextest` for faster test execution:
```bash
# Install nextest (if not already installed)
cargo install cargo-nextest
# Run tests
cargo nextest run
```
Or use standard cargo test:
```bash
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](LICENSE) file for details.
## Acknowledgments
- Built with [Rust](https://www.rust-lang.org/)
- Uses the excellent [image](https://github.com/image-rs/image) crate for image processing
- CLI powered by [clap](https://github.com/clap-rs/clap)
- Logging with [tracing](https://github.com/tokio-rs/tracing)
## Support
If you encounter any issues or have questions, please [open an issue](https://github.com/yourusername/instafy/issues) on GitHub.
---
Made with ❤️ and Rust