# Smart Image Cropper
[](https://badge.fury.io/py/smart-image-cropper)
[](https://pypi.org/project/smart-image-cropper/)
[](https://opensource.org/licenses/MIT)
An intelligent image cropping library that automatically detects objects in
images and creates optimized crops or collages. The library uses AI-powered
bounding box detection to identify the most important regions in your images and
intelligently crops them to standard aspect ratios.
## Features
- 🎯 **Smart Object Detection**: Automatically detects important objects in
images using AI
- 🖼️ **Intelligent Cropping**: Crops images to optimal aspect ratios (4:5, 3:4,
1:1, 4:3)
- 🎨 **Automatic Collages**: Creates beautiful collages when multiple objects
are detected
- 📐 **Aspect Ratio Optimization**: Automatically expands crops to reach target
aspect ratios
- 🔧 **Flexible Input**: Supports URLs, bytes, and PIL Images as input
- ⚡ **Fast Processing**: Efficient image processing with OpenCV
- 🐍 **Pure Python**: Easy to integrate into any Python project
- 🔄 **Multiple request modes**: Polling, webhook, single
## Installation
```bash
pip install smart-image-cropper
```
## Quick Start
```python
from smart_image_cropper import SmartImageCropper
# Initialize the cropper with your API credentials
cropper = SmartImageCropper(
api_url="your-api-endpoint",
api_key="your-api-key"
)
```
### Getting Bounding Boxes
The library supports three modes for getting bounding boxes:
1. **Polling** (default mode):
```python
# Automatically waits for job completion
bboxes = cropper.get_bounding_boxes(image_input, mode="polling")
```
2. **Webhook**:
```python
# Sends request and returns job ID
job_id = cropper.get_bounding_boxes(
image_input,
mode="webhook",
webhook_url="https://your-webhook.com"
)
# The webhook will receive results when the job is completed
# The webhook payload will contain bounding boxes in the format:
# {
# "delayTime": 1000,
# "executionTime": 1000,
# "input": {
# "image": "image_bytes",
# },
# "id": "job_123",
# "input": {
# "image": "image_bytes",
# },
# "status": "COMPLETED",
# "output": [
# {"x1": 0, "y1": 0, "x2": 100, "y2": 100},
# ...
# ],
# "webhook": "https://your-webhook.com"
# }
```
3. **Single Request**:
```python
# Only sends the request without waiting for results
cropper.get_bounding_boxes(image_input, mode="single")
```
### Creating a Collage
```python
# After getting bounding boxes
collage = cropper.create_collage(image_input, bboxes)
```
## Examples
### Complete Example with Polling
```python
from smart_image_cropper import SmartImageCropper
from PIL import Image
# Initialize the cropper
cropper = SmartImageCropper("https://api.example.com/detect", "your_api_key")
# Load the image
image = Image.open("example.jpg")
# Get bounding boxes (polling mode)
bboxes = cropper.get_bounding_boxes(image)
# Create the collage
result = cropper.create_collage(image, bboxes)
# Save the result
with open("result.jpg", "wb") as f:
f.write(result)
```
### Webhook Example with Flask
```python
from smart_image_cropper import SmartImageCropper, BoundingBox
from flask import Flask, request
app = Flask(__name__)
cropper = SmartImageCropper("https://api.example.com/detect", "your_api_key")
@app.route("/process", methods=["POST"])
def process_image():
image = request.files["image"]
job_id = cropper.get_bounding_boxes(
image.read(),
mode="webhook",
webhook_url="https://your-server.com/webhook"
)
return {"job_id": job_id}
@app.route('/webhook', methods=['POST'])
def webhook():
data = request.json
job_id = data.get('id')
if job_id and data.get('status') == 'COMPLETED':
# Parse bounding boxes from the webhook data
bboxes = [
BoundingBox(
x1=bbox['x1'],
y1=bbox['y1'],
x2=bbox['x2'],
y2=bbox['y2']
)
for bbox in data.get('output', [])
]
webhook_results[job_id] = bboxes
return jsonify({'status': 'ok'})
```
## Notes
- Polling mode is the simplest to use but may block execution for a while
- Webhook mode is ideal for asynchronous applications or web servers
- Single mode is useful when you just want to send the request without waiting
for results
## How It Works
1. The library sends the image to an AI-powered API for object detection
2. The API returns bounding boxes for detected objects
3. The library selects the best bounding boxes based on size and position
4. The image is cropped or a collage is created based on the selected boxes
5. The result is returned as image bytes
## Installation
```bash
pip install smart-image-cropper
```
## License
MIT
## Dependencies
- **OpenCV** (`opencv-python>=4.5.0`) - Image processing
- **NumPy** (`numpy>=1.20.0`) - Numerical operations
- **Pillow** (`Pillow>=8.0.0`) - PIL Image support
- **Requests** (`requests>=2.25.0`) - HTTP API calls
## Development
### Setting Up Development Environment
```bash
# Clone the repository
git clone https://github.com/yourusername/smart-image-cropper.git
cd smart-image-cropper
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black .
# Type checking
mypy smart_image_cropper/
```
### Running Tests
```bash
pytest tests/ -v --cov=smart_image_cropper
```
## 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.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
for details.
## Changelog
### v1.0.0
- Initial release
- Support for URL, bytes, and PIL Image inputs
- Automatic object detection and smart cropping
- Collage creation for multiple objects
- Aspect ratio optimization
## Support
If you encounter any issues or have questions, please file an issue on the
[GitHub issue tracker](https://github.com/yourusername/smart-image-cropper/issues).
## Acknowledgments
- OpenCV community for excellent image processing tools
- PIL/Pillow developers for image handling capabilities
- The Python packaging community for excellent tools and documentation
Raw data
{
"_id": null,
"home_page": "https://github.com/giumanuz/image_cropper",
"name": "smart-image-cropper",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Giulio Manuzzi <giuliomanuzzi@gmail.com>",
"keywords": "image processing, cropping, collage, computer vision, opencv",
"author": "Giulio Manuzzi",
"author_email": "Giulio Manuzzi <giuliomanuzzi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4f/cd/f035411c89bd04757ec43e382ec167802ed94a436f38e0eb4dd4f6683cde/smart_image_cropper-1.2.0.tar.gz",
"platform": null,
"description": "# Smart Image Cropper\n\n[](https://badge.fury.io/py/smart-image-cropper)\n[](https://pypi.org/project/smart-image-cropper/)\n[](https://opensource.org/licenses/MIT)\n\nAn intelligent image cropping library that automatically detects objects in\nimages and creates optimized crops or collages. The library uses AI-powered\nbounding box detection to identify the most important regions in your images and\nintelligently crops them to standard aspect ratios.\n\n## Features\n\n- \ud83c\udfaf **Smart Object Detection**: Automatically detects important objects in\n images using AI\n- \ud83d\uddbc\ufe0f **Intelligent Cropping**: Crops images to optimal aspect ratios (4:5, 3:4,\n 1:1, 4:3)\n- \ud83c\udfa8 **Automatic Collages**: Creates beautiful collages when multiple objects\n are detected\n- \ud83d\udcd0 **Aspect Ratio Optimization**: Automatically expands crops to reach target\n aspect ratios\n- \ud83d\udd27 **Flexible Input**: Supports URLs, bytes, and PIL Images as input\n- \u26a1 **Fast Processing**: Efficient image processing with OpenCV\n- \ud83d\udc0d **Pure Python**: Easy to integrate into any Python project\n- \ud83d\udd04 **Multiple request modes**: Polling, webhook, single\n\n## Installation\n\n```bash\npip install smart-image-cropper\n```\n\n## Quick Start\n\n```python\nfrom smart_image_cropper import SmartImageCropper\n\n# Initialize the cropper with your API credentials\ncropper = SmartImageCropper(\n api_url=\"your-api-endpoint\",\n api_key=\"your-api-key\"\n)\n```\n\n### Getting Bounding Boxes\n\nThe library supports three modes for getting bounding boxes:\n\n1. **Polling** (default mode):\n\n```python\n# Automatically waits for job completion\nbboxes = cropper.get_bounding_boxes(image_input, mode=\"polling\")\n```\n\n2. **Webhook**:\n\n```python\n# Sends request and returns job ID\njob_id = cropper.get_bounding_boxes(\n image_input,\n mode=\"webhook\",\n webhook_url=\"https://your-webhook.com\"\n)\n\n# The webhook will receive results when the job is completed\n# The webhook payload will contain bounding boxes in the format:\n# {\n# \"delayTime\": 1000,\n# \"executionTime\": 1000,\n# \"input\": {\n# \"image\": \"image_bytes\",\n# },\n# \"id\": \"job_123\",\n# \"input\": {\n# \"image\": \"image_bytes\",\n# },\n# \"status\": \"COMPLETED\",\n# \"output\": [\n# {\"x1\": 0, \"y1\": 0, \"x2\": 100, \"y2\": 100},\n# ...\n# ],\n# \"webhook\": \"https://your-webhook.com\"\n# }\n```\n\n3. **Single Request**:\n\n```python\n# Only sends the request without waiting for results\ncropper.get_bounding_boxes(image_input, mode=\"single\")\n```\n\n### Creating a Collage\n\n```python\n# After getting bounding boxes\ncollage = cropper.create_collage(image_input, bboxes)\n```\n\n## Examples\n\n### Complete Example with Polling\n\n```python\nfrom smart_image_cropper import SmartImageCropper\nfrom PIL import Image\n\n# Initialize the cropper\ncropper = SmartImageCropper(\"https://api.example.com/detect\", \"your_api_key\")\n\n# Load the image\nimage = Image.open(\"example.jpg\")\n\n# Get bounding boxes (polling mode)\nbboxes = cropper.get_bounding_boxes(image)\n\n# Create the collage\nresult = cropper.create_collage(image, bboxes)\n\n# Save the result\nwith open(\"result.jpg\", \"wb\") as f:\n f.write(result)\n```\n\n### Webhook Example with Flask\n\n```python\nfrom smart_image_cropper import SmartImageCropper, BoundingBox\nfrom flask import Flask, request\n\napp = Flask(__name__)\ncropper = SmartImageCropper(\"https://api.example.com/detect\", \"your_api_key\")\n\n@app.route(\"/process\", methods=[\"POST\"])\ndef process_image():\n image = request.files[\"image\"]\n job_id = cropper.get_bounding_boxes(\n image.read(),\n mode=\"webhook\",\n webhook_url=\"https://your-server.com/webhook\"\n )\n return {\"job_id\": job_id}\n\n@app.route('/webhook', methods=['POST'])\ndef webhook():\n data = request.json\n job_id = data.get('id')\n if job_id and data.get('status') == 'COMPLETED':\n # Parse bounding boxes from the webhook data\n bboxes = [\n BoundingBox(\n x1=bbox['x1'],\n y1=bbox['y1'],\n x2=bbox['x2'],\n y2=bbox['y2']\n )\n for bbox in data.get('output', [])\n ]\n webhook_results[job_id] = bboxes\n return jsonify({'status': 'ok'})\n```\n\n## Notes\n\n- Polling mode is the simplest to use but may block execution for a while\n- Webhook mode is ideal for asynchronous applications or web servers\n- Single mode is useful when you just want to send the request without waiting\n for results\n\n## How It Works\n\n1. The library sends the image to an AI-powered API for object detection\n2. The API returns bounding boxes for detected objects\n3. The library selects the best bounding boxes based on size and position\n4. The image is cropped or a collage is created based on the selected boxes\n5. The result is returned as image bytes\n\n## Installation\n\n```bash\npip install smart-image-cropper\n```\n\n## License\n\nMIT\n\n## Dependencies\n\n- **OpenCV** (`opencv-python>=4.5.0`) - Image processing\n- **NumPy** (`numpy>=1.20.0`) - Numerical operations\n- **Pillow** (`Pillow>=8.0.0`) - PIL Image support\n- **Requests** (`requests>=2.25.0`) - HTTP API calls\n\n## Development\n\n### Setting Up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/smart-image-cropper.git\ncd smart-image-cropper\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nblack .\n\n# Type checking\nmypy smart_image_cropper/\n```\n\n### Running Tests\n\n```bash\npytest tests/ -v --cov=smart_image_cropper\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major\nchanges, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file\nfor details.\n\n## Changelog\n\n### v1.0.0\n\n- Initial release\n- Support for URL, bytes, and PIL Image inputs\n- Automatic object detection and smart cropping\n- Collage creation for multiple objects\n- Aspect ratio optimization\n\n## Support\n\nIf you encounter any issues or have questions, please file an issue on the\n[GitHub issue tracker](https://github.com/yourusername/smart-image-cropper/issues).\n\n## Acknowledgments\n\n- OpenCV community for excellent image processing tools\n- PIL/Pillow developers for image handling capabilities\n- The Python packaging community for excellent tools and documentation\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An intelligent image cropping library that creates smart collages",
"version": "1.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/giumanuz/smart-image-cropper/issues",
"Documentation": "https://github.com/giumanuz/smart-image-cropper#readme",
"Homepage": "https://github.com/giumanuz/smart-image-cropper",
"Repository": "https://github.com/giumanuz/smart-image-cropper"
},
"split_keywords": [
"image processing",
" cropping",
" collage",
" computer vision",
" opencv"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b1ee6027feffce85d9833971c0bab77a93ffaa9dbf2adb098822a41ec8dd5e9",
"md5": "7b8d68fc96902e6326903447fd089d1c",
"sha256": "2c073a066d1f31b55aff9196d62733ce09aa1d680aea261d20a55a760b35a7ff"
},
"downloads": -1,
"filename": "smart_image_cropper-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b8d68fc96902e6326903447fd089d1c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12660,
"upload_time": "2025-07-15T19:24:24",
"upload_time_iso_8601": "2025-07-15T19:24:24.810998Z",
"url": "https://files.pythonhosted.org/packages/4b/1e/e6027feffce85d9833971c0bab77a93ffaa9dbf2adb098822a41ec8dd5e9/smart_image_cropper-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4fcdf035411c89bd04757ec43e382ec167802ed94a436f38e0eb4dd4f6683cde",
"md5": "dcd4825c59e303b97b8ec97336812382",
"sha256": "b57251d9af9834060a9111a04f3d5339b95fc27fa05e4fdc61134d8acc11337b"
},
"downloads": -1,
"filename": "smart_image_cropper-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "dcd4825c59e303b97b8ec97336812382",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24480,
"upload_time": "2025-07-15T19:24:26",
"upload_time_iso_8601": "2025-07-15T19:24:26.235468Z",
"url": "https://files.pythonhosted.org/packages/4f/cd/f035411c89bd04757ec43e382ec167802ed94a436f38e0eb4dd4f6683cde/smart_image_cropper-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 19:24:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "giumanuz",
"github_project": "image_cropper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "opencv-python",
"specs": [
[
">=",
"4.5.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.20.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
}
],
"lcname": "smart-image-cropper"
}
JSON
