Image Magic Suite

Image Magic Suite (PyPI: image-magic-suite) — an all-in-one Python package for:

• Background removal (rembg + OpenCV fallback)
• Smart background detection & blending
• Smart cropping (object-aware)
• Auto color correction
• Resize & compress to target file size
• Optional AI upscaling (Real-ESRGAN integration)
• Batch processing, caching, CLI & FastAPI

Table of Contents

• Features
• Install
• Quickstart (CLI)
• Quickstart (API)
• Examples
• Why choose Image Magic Suite?
• Contributing
• License

Features

• Hybrid background removal: uses rembg when available, else OpenCV mask.
• Smart blend and auto-detect background style (light/dark).
• Smart crop extracts main object.
• Auto color correction for contrast and white balance.
• Resize + compress to target KB with iterative quality and smart resize.
• Optional AI upscale via Real-ESRGAN (GPU/CPU aware).
• Persistent caching (SHA256-based) to avoid repeat processing.
• Batch processing with multi-file convenience.
• CLI image-tools and FastAPI server to expose endpoints.

Install

# Recommended: create a venv
python -m venv venv
source venv/bin/activate  # windows: venv\Scripts\activate

# Install runtime dependencies
pip install -r requirements.txt

# Install as editable package for development
pip install -e .

Optional AI extras

pip install image-magic-suite[ai]
# or install torch + realesrgan manually as required

---

Why choose Image Magic Suite?

• Easy to integrate in pipelines (CLI, Python import, REST API).

• Production-minded: caching, batch, fallback logic.

• Supports optional AI models for best-in-class upscaling.

Contributing

• Open a PR, add tests, follow PEP8. See docs/CONTRIBUTING.md (future).

License

• MIT — see LICENSE file.

---

## 6) Documentation files

### 6a) `docs/index.md`  
(📄 file: `docs/index.md`) — Project overview + architecture.

# Image Magic Suite — Documentation

Welcome to Image Magic Suite docs.

## Project Overview
Image Magic Suite brings together robust, production-ready tools for image preprocessing:
- Background removal
- Smart cropping / blending
- Color correction
- Resize & quality-preserving compression
- Optional AI upscaling (Real-ESRGAN)

## Architecture (high level)
- `src/image_magic_suite/processor.py` — single entry point helper functions wrapping lower-level modules.
- Low-level modules:
  - `background_remove.py` — remove or mask backgrounds.
  - `smart_blend.py` — automatic blending and background heuristics.
  - `smart_crop.py` — crop to object bbox.
  - `color_correct.py` — color-balancing helpers.
  - `esrgan_upscale.py` — AI-based upscaling (optional).
  - `cache.py` — persistent cache to avoid recompute.
  - `batch.py` — utilities for batch runs.
- `api/main.py` — FastAPI endpoints for server usage.
- `cli.py` — command line interface.

## Use Cases
- E-commerce product photo preprocessing
- Bulk image pipelines
- SaaS image microservice backends

---

6b) docs/install.md

• (📄 file: docs/install.md) — Installation instructions & environment tips.

	# Installation

	## 1. Create virtual environment
	```bash
	python -m venv venv
	source venv/bin/activate
	```

---

2. Install base requirements

pip install -r requirements.txt

---

3. Install package (dev)

pip install -e .

---

4. Optional: AI extras

• Install PyTorch and Real-ESRGAN according to your GPU/CPU configuration:

pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/cu118
pip install realesrgan

---

5. Verify

python -c "import image_magic_suite; print(image_magic_suite.__version__)"

	### 6c) `docs/api.md`  
	(📄 file: `docs/api.md`) — Endpoint list, payloads, and examples.

	```markdown
	
	# API Documentation

	Start server:
	```

• uvicorn api.main:app --reload --port 8000

## Endpoints
### POST /remove-background
- Accepts multipart file `file`
- Returns PNG image bytes (application/octet-stream) or JSON with hex-encoded bytes.

Example (curl):
	```bash
	curl -X POST "http://localhost:8000/remove-background" -F "file=@input.jpg" -o out.png
	```

---

6d) docs/cli.md

• (📄 file: docs/cli.md) — CLI flags & examples.

# CLI

Usage:

---

6e) docs/ui.md

• (📄 file: docs/ui.md) — This file documents a future minimal UI and how to hook it to the API.

---

7) scripts/auto_install.sh

• (📄 file: scripts/auto_install.sh) — 2-line: automates venv + installs including optional AI comment.

#!/usr/bin/env bash
set -e

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

echo "Base install complete."
echo "To enable AI upscale, install extras:"
echo "  pip install image-magic-suite[ai] or pip install torch realesrgan"

---

8) Source package: src/image_magic_suite/*

| Note: use image_magic_suite (underscore) as the Python module name for import safety.

8a) init.py

• (📄 file: src/image_magic_suite/init.py) — 2-line: exports, version, safe imports.

"""
image_magic_suite — public API
"""

__version__ = "0.1.0"

from .processor import (
    remove_background,
    add_background,
    smart_crop,
    auto_color_correct,
    resize_image,
    compress_to_target_kb,
    enhance_image,
)
from .esrgan_upscale import ai_upscale_if_available

__all__ = [
    "remove_background",
    "add_background",
    "smart_crop",
    "auto_color_correct",
    "resize_image",
    "compress_to_target_kb",
    "enhance_image",
    "ai_upscale_if_available",
]

---