Metadata-Version: 2.4
Name: imageconvert
Version: 0.3.2
Summary: A Python library for converting between different image formats with metadata preservation
Author-email: mricardo <ricardo.lee.cm@gmail.com>
Maintainer-email: mricardo <ricardo.lee.cm@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mricardo888/ImageConvert
Project-URL: Bug Tracker, https://github.com/mricardo888/ImageConvert/issues
Project-URL: GitHub Docs, https://github.com/mricardo888/ImageConvert#readme
Project-URL: Documentation, https://ricardos-projects.gitbook.io/imageconvert-docs
Keywords: image,conversion,metadata,exif,photos,avif,heif,heic,webp,jfif,pdf
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3.7
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: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Multimedia :: Graphics :: Capture
Classifier: Topic :: Multimedia :: Graphics :: Viewers
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.3.0
Requires-Dist: pillow-heif>=0.13.0
Requires-Dist: piexif>=1.1.3
Requires-Dist: svglib>=1.2.0
Requires-Dist: reportlab>=3.6.0
Requires-Dist: rawpy>=0.17.0
Requires-Dist: PyMuPDF>=1.21.0
Requires-Dist: win32-setctime>=1.1.0; platform_system == "Windows"
Dynamic: license-file

# 🖼️ ImageConvert

[![PyPI version](https://img.shields.io/pypi/v/imageconvert.svg)](https://pypi.org/project/imageconvert/)
[![Python version](https://img.shields.io/pypi/pyversions/imageconvert.svg)](https://pypi.org/project/imageconvert/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/imageconvert)](https://pypi.org/project/imageconvert/)

**ImageConvert** is a robust Python library designed for seamless conversion between modern image formats and PDFs. Unlike basic converters, it prioritizes **data integrity**—preserving EXIF metadata, GPS coordinates, and original file timestamps during the process.

## ✨ Key Features

* **🔄 Universal Conversion:** Support for JPEG, PNG, WebP, HEIC/AVIF, TIFF, BMP, and more.
* **📄 PDF Power Tools:**
    * **PDF to Image:** Render PDF pages as high-quality images.
    * **Image to PDF:** Compile multiple images into a single document.
* **💾 Metadata Safe:** Preserves EXIF data (Camera model, ISO, GPS) during conversion.
* **⏱️ Time Travel:** Retains original file creation, access, and modification timestamps (Windows/Linux/macOS supported).
* **📂 Batch Processing:** Recursively convert entire folder structures with a single command.

## 📃 Full Documentation

For a complete guide on all classes, methods, and parameters, please see the [API Reference](docs/API_REFERENCE.md).

Explore the complete documentation and examples here:  
👉 [https://ricardos-projects.gitbook.io/imageconvert-docs](https://ricardos-projects.gitbook.io/imageconvert-docs)

## 📦 Installation

```bash
pip install imageconvert
```

*Note: This automatically installs necessary dependencies like `pillow-heif` (for AVIF/HEIC) and `pymupdf` (for PDF).*

## 🚀 Quick Start

### 1. Basic Conversion

Convert single images easily. Metadata is preserved by default.

```python
from imageconvert import ImageConvert

# Simple conversion
ImageConvert.convert("vacation.heic", "vacation.jpg")

# Conversion with quality control
ImageConvert.convert("input.png", "output.webp", quality=85)

```

### 2. PDF Operations

Handle PDF documents without external tools.

```python
# Extract all pages from a PDF as High-Res JPEGs
ImageConvert.pdf_to_images("contract.pdf", "output_folder", dpi=300)

# Create a PDF from a list of images (A4 size, contained fit)
ImageConvert.images_to_pdf(
    ["scan1.jpg", "scan2.jpg"], 
    "combined_doc.pdf",
    fit_method="contain"
)

```

### 3. Batch Processing

Convert an entire directory tree. Useful for optimizing libraries or web assets.

```python
ImageConvert.batch_convert(
    input_dir="./raw_photos", 
    output_dir="./web_ready", 
    output_format=".webp", 
    recursive=True,      # Process subfolders
    skip_existing=True   # Resume interrupted jobs
)

```

### 4. Extracting Metadata

Get technical details, including GPS coordinates and PDF info.

```python
info = ImageConvert.get_image_info("photo.jpg")

print(f"Camera: {info.get('camera')}")
# Output: {'make': 'Apple', 'model': 'iPhone 13 Pro', 'exposure': {'iso': 120...}}

if 'gps' in info:
    print(f"Location: {info['gps']}")
    # Output: {'latitude': 40.7128, 'longitude': -74.0060}

```

## 🩰 Supported Formats

| Format | Extension | Read | Write | Notes |
| --- | --- | --- | --- | --- |
| **JPEG** | `.jpg`, `.jpeg`, `.jfif` | ✅ | ✅ | Optimized encoding |
| **PNG** | `.png` | ✅ | ✅ | Lossless |
| **WebP** | `.webp` | ✅ | ✅ | Google's web format |
| **HEIC** | `.heic`, `.heif` | ✅ | ✅ | iOS High Efficiency |
| **AVIF** | `.avif` | ✅ | ✅ | Next-gen compression |
| **TIFF** | `.tiff`, `.tif` | ✅ | ✅ | High quality archival |
| **PDF** | `.pdf` | ✅ | ✅ | Multi-page support |
| **RAW** | `.raw` | ✅ | ❌ | Read-only |
| **SVG** | `.svg` | ✅ | ❌ | Read-only |
| **BMP** | `.bmp` | ✅ | ✅ | Basic bitmap |

## 🤝 Contributing

Contributions are welcome! Please visit the [GitHub Repository](https://github.com/mricardo888/ImageConvert) to report bugs or submit pull requests.

## 📄 License

This project is licensed under the **[MIT License](LICENSE)**.
