SoftCropper

SoftCropper is a powerful CLI tool that transforms rectangular images into square, print-ready formats with aesthetic borders and customizable text annotations — built for precision and automation.

Actively used by CanvasMagnet for order prep and A4 layout automation.

📸 Example Results

Before	➡️	After
Baby.webp (600×900)		Output (900×900)
Kid.jpg (1100×733)		Output (1100×1100)

A4:

🚀 Features

• ✅ Auto-square images with optional blurred/solid/gradient padding
• 🖼️ Add customizable rounded borders around photos
• ✍️ Annotate left/right/top/bottom with vertical or centered text (great for branding)
• 📄 Generate auto-arranged A4 collage pages from processed photos
• 📐 Resize final output by target size (e.g. --size 5.5x5.5cm or --size 55x55mm)
• 🧪 Includes CLI, Makefile, tests, and PyPI packaging

📦 Requirements

• Python >= 3.7
• opencv-python
• numpy

🔧 Installation

pip install softcropper

For local development:

make venv
make install

⚙️ CLI Usage

softcropper ./input_photos --mode blur --border --text \
  --left "@CanvaMagnet" \
  --right "+971 545800462" \
  --top "Preview" \
  --bottom "www.CanvaMagnet.com" \
  --size 5.5x5.5cm \
  --a4

Options

✅ Testing

make test

Or manually:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest tests/ -v

🛠️ Makefile Commands

make venv         # Create .venv
make install      # Install locally in editable mode
make test         # Run tests
make build        # Build wheel and source dist
make deploy       # Deploy to PyPI
make clean        # Remove virtualenv + build artifacts

📄 Changelog

See CHANGELOG.md

🤝 Contribution

Pull requests are welcome! Open an issue or fork and submit a PR if you'd like to improve SoftCropper.

Author

Khaled Alam
📧 khaledalam.net@gmail.com
🌍 Website | LinkedIn | Twitter/X