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.
| Before | ➡️ | After |
|---|---|---|
Baby.webp (600×900) |
Output (900×900) |
|
Kid.jpg (1100×733) |
Output (1100×1100) |
A4:
- ✅ 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.5cmor--size 55x55mm) - 🧪 Includes CLI, Makefile, tests, and PyPI packaging
- Python
>= 3.7 opencv-pythonnumpy
pip install softcropperFor local development:
make venv
make installsoftcropper ./input_photos --mode blur --border --text \
--left "@CanvaMagnet" \
--right "+971 545800462" \
--top "Preview" \
--bottom "www.CanvaMagnet.com" \
--size 5.5x5.5cm \
--a4| Flag | Description |
|---|---|
--mode |
One of: blur (default), solid, gradient |
--border |
Add rounded frame around photo |
--text |
Enable text mode (requires at least one --left/right/top/bottom) |
--left |
Vertical text on left side |
--right |
Vertical text on right side |
--top |
Centered text above the image |
--bottom |
Centered text below the image |
--size |
Resize output image (supports mm or cm, e.g. 55x55mm) |
--a4 |
Generate A4 page(s) from processed images |
make testOr manually:
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest tests/ -vmake 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 artifactsSee CHANGELOG.md
Pull requests are welcome! Open an issue or fork and submit a PR if you'd like to improve SoftCropper.
Khaled Alam
📧 khaledalam.net@gmail.com
🌍 Website | LinkedIn | Twitter/X