smart-image-cropper 1.0.0__tar.gz

smart_image_cropper-1.0.0/.gitignore

@@ -0,0 +1,144 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Test images
+test_images/
+*.jpg
+*.png
+*.jpeg

smart_image_cropper-1.0.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2024 Smart Image Cropper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

smart_image_cropper-1.0.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include requirements.txt
+include pyproject.toml
+recursive-include smart_image_cropper *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .DS_Store 

smart_image_cropper-1.0.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: smart-image-cropper
+Version: 1.0.0
+Summary: An intelligent image cropping library that creates smart collages
+Home-page: https://github.com/giumanuz/image_cropper
+Author: Giulio Manuzzi
+Author-email: Your Name <your.email@example.com>
+Maintainer-email: Your Name <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/smart-image-cropper
+Project-URL: Documentation, https://github.com/yourusername/smart-image-cropper#readme
+Project-URL: Repository, https://github.com/yourusername/smart-image-cropper
+Project-URL: Bug Tracker, https://github.com/yourusername/smart-image-cropper/issues
+Keywords: image processing,cropping,collage,computer vision,opencv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: Pillow>=8.0.0
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8; extra == "dev"
+Requires-Dist: mypy>=0.812; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Smart Image Cropper
+
+[![PyPI version](https://badge.fury.io/py/smart-image-cropper.svg)](https://badge.fury.io/py/smart-image-cropper)
+[![Python Support](https://img.shields.io/pypi/pyversions/smart-image-cropper.svg)](https://pypi.org/project/smart-image-cropper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
+
+## Installation
+
+```bash
+pip install smart-image-cropper
+```
+
+## Quick Start
+
+```python
+from smart_image_cropper import SmartImageCropper
+from PIL import Image
+
+# Initialize the cropper with your API credentials
+cropper = SmartImageCropper(
+    api_url="your-api-endpoint",
+    api_key="your-api-key"
+)
+
+# Method 1: Process from URL
+result_bytes = cropper.process_image("https://example.com/image.jpg")
+
+# Method 2: Process from bytes
+with open("image.jpg", "rb") as f:
+    image_bytes = f.read()
+result_bytes = cropper.process_image(image_bytes)
+
+# Method 3: Process from PIL Image
+pil_image = Image.open("image.jpg")
+result_bytes = cropper.process_image(pil_image)
+
+# Save the result
+with open("cropped_result.jpg", "wb") as f:
+    f.write(result_bytes)
+```
+
+## How It Works
+
+1. **Object Detection**: The library sends your image to an AI-powered bounding
+   box detection API
+2. **Smart Selection**: Identifies the most important objects based on size and
+   relevance
+3. **Intelligent Processing**:
+   - **Single Object**: Crops and expands to the nearest standard aspect ratio
+   - **Multiple Objects**: Creates a collage with optimal layout
+     (vertical/horizontal)
+4. **Aspect Ratio Optimization**: Ensures the final result matches standard
+   social media formats
+
+## Supported Aspect Ratios
+
+- **Portrait 4:5** (0.8) - Instagram posts
+- **Portrait 3:4** (0.75) - Traditional photo format
+- **Square 1:1** (1.0) - Instagram square posts
+- **Landscape 4:3** (1.33) - Traditional landscape format
+
+## API Requirements
+
+This library requires access to a bounding box detection API. The API should:
+
+- Accept POST requests with JSON payload containing base64-encoded images
+- Return a job ID for asynchronous processing
+- Provide a status endpoint to check job completion
+- Return bounding box coordinates in the format:
+  `{"x1": int, "y1": int, "x2": int, "y2": int}`
+
+### Example API Integration
+
+```python
+# Your API should accept this format:
+{
+    "input": {
+        "image": "base64-encoded-image-string"
+    }
+}
+
+# And return:
+{
+    "id": "job-id-string"
+}
+
+# Status check should return:
+{
+    "status": "COMPLETED",  # or "FAILED"
+    "output": [
+        {"x1": 100, "y1": 50, "x2": 300, "y2": 250},
+        {"x1": 400, "y1": 100, "x2": 600, "y2": 300}
+    ]
+}
+```
+
+## Advanced Usage
+
+### Error Handling
+
+```python
+from smart_image_cropper import SmartImageCropper, SmartCropperError, APIError
+
+try:
+    cropper = SmartImageCropper(api_url="...", api_key="...")
+    result = cropper.process_image("image.jpg")
+except APIError as e:
+    print(f"API Error: {e}")
+except SmartCropperError as e:
+    print(f"Processing Error: {e}")
+```
+
+### Logging
+
+The library uses Python's logging module. Enable debug logging to see detailed
+processing information:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+# Now you'll see detailed processing logs
+```
+
+## 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

smart_image_cropper-1.0.0/PUBLISHING_GUIDE.md

@@ -0,0 +1,262 @@
+# Publishing Smart Image Cropper to PyPI
+
+This guide will walk you through the process of publishing your Smart Image
+Cropper library to PyPI (Python Package Index).
+
+## Prerequisites
+
+1. **Python 3.8+** installed
+2. **Git** installed and configured
+3. **PyPI account** - Sign up at
+   [https://pypi.org/account/register/](https://pypi.org/account/register/)
+4. **TestPyPI account** (optional but recommended) - Sign up at
+   [https://test.pypi.org/account/register/](https://test.pypi.org/account/register/)
+
+## Step 1: Set Up Your Development Environment
+
+```bash
+# Clone your repository (or navigate to your project directory)
+cd smart-image-cropper
+
+# Create a virtual environment
+python -m venv venv
+
+# Activate virtual environment
+# On Windows:
+venv\Scripts\activate
+# On macOS/Linux:
+source venv/bin/activate
+
+# Install build tools
+pip install --upgrade pip setuptools wheel twine build
+
+# Install your package in development mode
+pip install -e ".[dev]"
+```
+
+## Step 2: Update Package Information
+
+Before publishing, make sure to update the following files with your actual
+information:
+
+### 1. Update `setup.py` and `pyproject.toml`
+
+Replace placeholder information:
+
+- `author="Your Name"`
+- `author_email="your.email@example.com"`
+- `url="https://github.com/yourusername/smart-image-cropper"`
+- All GitHub URLs with your actual repository URLs
+
+### 2. Update `smart_image_cropper/__init__.py`
+
+- Update `__author__` and `__email__` fields
+
+## Step 3: Test Your Package Locally
+
+```bash
+# Run tests (if you have them)
+pytest
+
+# Check if your package can be built
+python -m build
+
+# This should create files in dist/ directory:
+# - smart_image_cropper-1.0.0-py3-none-any.whl
+# - smart_image_cropper-1.0.0.tar.gz
+```
+
+## Step 4: Validate Your Package
+
+```bash
+# Check your package with twine
+twine check dist/*
+
+# This should show "PASSED" for all checks
+```
+
+## Step 5: Test on TestPyPI (Recommended)
+
+TestPyPI is a separate instance of PyPI for testing packages.
+
+```bash
+# Upload to TestPyPI first
+twine upload --repository testpypi dist/*
+
+# You'll be prompted for your TestPyPI credentials
+# Username: your-testpypi-username
+# Password: your-testpypi-password (or token)
+```
+
+### Test Installation from TestPyPI
+
+```bash
+# Create a new environment to test installation
+python -m venv test_env
+source test_env/bin/activate  # or test_env\Scripts\activate on Windows
+
+# Install from TestPyPI
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ smart-image-cropper
+
+# Test that it works
+python -c "from smart_image_cropper import SmartImageCropper; print('Import successful!')"
+```
+
+## Step 6: Publish to PyPI
+
+Once you've tested on TestPyPI and everything works:
+
+```bash
+# Upload to the real PyPI
+twine upload dist/*
+
+# Enter your PyPI credentials when prompted
+```
+
+## Step 7: Set Up API Tokens (Recommended)
+
+For better security, use API tokens instead of username/password:
+
+1. Go to
+   [https://pypi.org/manage/account/token/](https://pypi.org/manage/account/token/)
+2. Create a new token with scope limited to your project
+3. Configure your `~/.pypirc` file:
+
+```ini
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-your-api-token-here
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-your-testpypi-token-here
+```
+
+## Step 8: Automate with GitHub Actions (Optional)
+
+Create `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.8"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*
+```
+
+Then add your PyPI API token as a secret in your GitHub repository:
+
+1. Go to your repo settings → Secrets and variables → Actions
+2. Add a new secret named `PYPI_API_TOKEN` with your token value
+
+## Step 9: Update Version for Future Releases
+
+For subsequent releases:
+
+1. **Update version number** in:
+
+   - `setup.py`
+   - `pyproject.toml`
+   - `smart_image_cropper/__init__.py`
+
+2. **Clean previous builds**:
+
+   ```bash
+   rm -rf dist/ build/ *.egg-info/
+   ```
+
+3. **Build and upload new version**:
+   ```bash
+   python -m build
+   twine upload dist/*
+   ```
+
+## Common Issues and Solutions
+
+### Issue: Package name already exists
+
+- Choose a different name or add a prefix/suffix
+- Update the `name` field in `setup.py` and `pyproject.toml`
+
+### Issue: Upload fails with authentication error
+
+- Make sure you're using the correct credentials
+- Try using API tokens instead of username/password
+- Check if 2FA is enabled on your account
+
+### Issue: "File already exists" error
+
+- You're trying to upload the same version twice
+- Update the version number and rebuild
+
+### Issue: Import errors after installation
+
+- Check that all dependencies are correctly specified
+- Verify the package structure matches the imports
+
+## Verification After Publishing
+
+1. **Check your package page**: `https://pypi.org/project/smart-image-cropper/`
+2. **Test installation**:
+   ```bash
+   pip install smart-image-cropper
+   python -c "from smart_image_cropper import SmartImageCropper; print('Success!')"
+   ```
+3. **Test in a fresh environment** to ensure all dependencies are properly
+   specified
+
+## Best Practices
+
+1. **Always test on TestPyPI first**
+2. **Use semantic versioning** (MAJOR.MINOR.PATCH)
+3. **Keep detailed changelog** in README.md
+4. **Use API tokens** instead of passwords
+5. **Automate with CI/CD** for consistent releases
+6. **Tag your releases** in Git:
+   ```bash
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+
+## Resources
+
+- [PyPI Official Packaging Tutorial](https://packaging.python.org/tutorials/packaging-projects/)
+- [Twine Documentation](https://twine.readthedocs.io/)
+- [Setuptools Documentation](https://setuptools.readthedocs.io/)
+- [Python Packaging User Guide](https://packaging.python.org/)
+
+---
+
+🎉 **Congratulations!** Your Smart Image Cropper library is now available for
+the world to use via `pip install smart-image-cropper`!