Metadata-Version: 2.4
Name: snapforge
Version: 4.0.0
Summary: Powerful and fast image editor! 😎
Author: Ali.Shm
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: Pillow>=9.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: packaging>=20.0

# 📸 SnapForge

[![PyPI](https://img.shields.io/pypi/v/snapforge)](https://pypi.org/project/snapforge/)
[![Python](https://img.shields.io/pypi/pyversions/snapforge)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Made with Pillow](https://img.shields.io/badge/Built%20With-Pillow-blue)](https://python-pillow.org/)
[![Status](https://img.shields.io/badge/status-active-success)](https://github.com/)

> **Forge your images with a single chain of commands.**

A lightweight, fast and intuitive Python library for image processing built on top of Pillow.

Perfect for compressing, resizing, filtering, enhancing and transforming images.

## ✨ Features

- 🖼️ Load and create images
- 📐 Resize and transform images
- 🔄 Advanced format conversion
- 🎨 Image mode conversion
- 💾 Save and optimize images
- 🪄 Image effects
- 🧩 Image overlays
- 🎬 Image motion and animation
- 🔍 Image inspection
- 🔄 Update checking
- 🔗 Chainable API design
- 🧾 MIT License

## 🔄 Professional Format Converter 🔄

The `convert` method (`Storage.convert`) supports **more than 8 formats**:

JPEG, JPG, PNG, WEBP, GIF, TIFF, BMP, ICO and more.

SnapForge supports common Pillow modes such as:

- `RGB`
- `RGBA`
- `L`
- `LA`
- `P`
- `CMYK`
- `1`

## 📦 Installation

You can install SnapForge directly from PyPI using `pip`:

```bash
pip install snapforge
```

Or if you have already installed it:

```bash
pip install snapforge --upgrade
```

## 🚀 Quick Start

Here is a quick example to get you started with SnapForge:

```python
from snapforge import Storage, Geometry, SnapForgeUpdater

version = "your_version"

updater = SnapForgeUpdater("snapforge", version)

updater.start_check()

# Complete image path
img = Storage.load(r"...\my_image.jpeg")

img = Storage.convert_mode(img, "RGB")

img = Geometry.round_corners(img, 40)

img = Storage.convert(img, "png")

# Complete image path
img = Storage.save(
    img,
    r"...\my_rounded_image.png"
)
```

# 📖 Available Modules

SnapForge is now **fully modular** 🔧 — each module has a single responsibility and can be imported independently:

```python
from snapforge import (
    Storage,
    Geometry,
    Effects,
    Overlays,
    Motion,
    Inspector,
    SnapForgeUpdater
)
```

- 📐 **Geometry** — resizing, cropping, rotating and transforming
- 💾 **Storage** — loading, saving and format conversion
- 🔍 **Inspector** — metadata, histogram and color analysis
- 🎨 **Effects** — lighting and filters
- 🖼️ **Overlays** — text, watermark, borders and blending
- 🎬 **Motion** — creating slide and bounce animations
- 🔄 **SnapForgeUpdater** — update checks and version comparison

# 📦 Available Methods

Here is the complete list of all available methods in each **snapforge** module:

### 📐 Geometry

| Method | Description | Example |
| --- | --- | --- |
| `Geometry.resize(img, w, h)` | Change image dimensions | `Geometry.resize(img, 800, 600)` |
| `Geometry.thumbnail(img, w, h)` | Resize while keeping aspect ratio | `Geometry.thumbnail(img, 500, 500)` |
| `Geometry.fit(img, w, h)` | Resize and crop to exact dimensions | `Geometry.fit(img, 1080, 1080)` |
| `Geometry.crop(img, l, t, r, b)` | Crop image | `Geometry.crop(img, 0, 0, 100, 100)` |
| `Geometry.rotate(img, a)` | Rotate image | `Geometry.rotate(img, 90)` |
| `Geometry.flip(img, dir)` | Flip image | `Geometry.flip(img, "horizontal")` |
| `Geometry.round_corners(img, radius)` | Round image corners | `Geometry.round_corners(img, 40)` |

---

### 💾 Storage

| Method | Description | Example |
| --- | --- | --- |
| `Storage.load(path)` | Load image from file | `Storage.load("photo.jpg")` |
| `Storage.save(img, name)` | Save image | `Storage.save(img, "result.jpg")` |
| `Storage.convert(img, fmt)` | Change image format (PNG, JPG, WEBP…) | `Storage.convert(img, "PNG")` |
| `Storage.optimize(img, q)` | Set JPEG quality | `Storage.optimize(img, 85)` |
| `Storage.convert_mode(img, mode)` | Change image color mode | `Storage.convert_mode(img, "RGB")` |
| `Storage.new(mode, size, color)` | Make a new image but don't save it | `Storage.new("RGB", (800, 600), "white")` |

---

### 🎬 Motion

| Method | Description | Example |
| --- | --- | --- |
| `Motion.slide(img, direction, frames, duration)` | Create a one-way motion animation | `Motion.slide(img, "left", 30, 100)` |
| `Motion.bounce(img, direction, frames, duration)` | Create a forward and backward motion animation | `Motion.bounce(img, "horizontal", 30, 100)` |

#### Supported `Motion.slide` directions:

- `left`
- `right`
- `up`
- `down`

#### Supported `Motion.bounce` directions:

- `horizontal`
- `vertical`


---

### 🔍 Inspector

| Method | Description | Example |
| --- | --- | --- |
| `Inspector.get_metadata(img)` | Extract detailed image metadata | `Inspector.get_metadata(img)` |
| `Inspector.histogram(img)` | Generate histogram data | `Inspector.histogram(img)` |
| `Inspector.compare(img)` | Display metadata and processing summary | `Inspector.compare(img)` |
| `Inspector.extract_color_palette(img)` | Get dominant colors as Hex codes | `Inspector.extract_color_palette(img)` |

---

### 🎨 Effects (Lighting & Filters)

| Method | Description | Example |
| --- | --- | --- |
| `Effects.apply_brightness(img, f)` | Adjust brightness | `Effects.apply_brightness(img, 1.2)` |
| `Effects.apply_contrast(img, f)` | Adjust contrast | `Effects.apply_contrast(img, 1.5)` |
| `Effects.auto_enhance(img)` | Improve brightness, contrast and sharpness | `Effects.auto_enhance(img)` |
| `Effects.invert(img)` | Invert image colors | `Effects.invert(img)` |
| `Effects.apply_sepia(img)` | Classic sepia effect | `Effects.apply_sepia(img)` |
| `Effects.apply_grayscale(img, f)` | Convert to grayscale | `Effects.apply_grayscale(img, 1.0)` |
| `Effects.apply_blur(img, r)` | Gaussian blur | `Effects.apply_blur(img, 5.0)` |
| `Effects.apply_sharpen(img, f)` | Sharpen image | `Effects.apply_sharpen(img, 1.0)` |
| `Effects.apply_camscanner(img)` | Document scanner effect | `Effects.apply_camscanner(img)` |
| `Effects.apply_preset(img, name)` | Apply a professional preset | `Effects.apply_preset(img, "vintage")` |

### Supported presets (`Effects.apply_preset`):

`vintage`, `cinematic`, `vibrant`, `dreamy`, `noir`, `warm`, `cool`

---

### 🖼️ Overlays

| Method | Description | Example |
| --- | --- | --- |
| `Overlays.add_watermark(img, path)` | Add watermark | `Overlays.add_watermark(img, "logo.png")` |
| `Overlays.add_text(img, text, pos)` | Draw text | `Overlays.add_text(img, "Hello!", (50, 50))` |
| `Overlays.add_border(img, size, color)` | Add border | `Overlays.add_border(img, 10, (0, 0, 0))` |
| `Overlays.double_exposure(img, img2, mode)` | Blend with another image | `Overlays.double_exposure(img, "layer.png", "blend")` |

---

### 🔄 SnapForgeUpdater

| Method | Description | Example |
| --- | --- | --- |
| `SnapForgeUpdater.__init__(package_name, current_version)` | Initialize the updater with the package name and current version | `SnapForgeUpdater("snapforge", "3.0.0")` |

#### To check updates run:

```python
updater = SnapForgeUpdater("snapforge", "your_version")

updater.start_check()
```

## 🛠️ Requirements

To use `SnapForge`, ensure you have the following installed:

- **Python:** 3.14 or higher

- **Dependencies:**
  - `Pillow` (for image processing)
  - `requests` (for automatic update checks)
  - `packaging` (for version comparison logic)

## 🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

## 🌟 More Projects

If you enjoy SnapForge, you might also like these projects, too:

### PixSlim

A Python image, PDF, Word and ... compression library focused on reducing file size while preserving quality.

### turtle-shape

The Turtle_Shape library provides ready-made shapes and tools for creating graphics and drawings with Python's Turtle module.

## 📜 License

Distributed under the MIT License.

## ❤️ Support

If you find SnapForge useful, your support means a lot!

You can help by:

- 📦 Installing the package and trying it in your projects
- 📝 Sharing feedback and suggestions
- 🐛 Reporting bugs and improvements
- 🌟 Recommending SnapForge to other Python developers

🧩 Every piece of feedback helps make SnapForge better. 🙏

## 👤 Author

### Ali.Shm

**Project Maintainer**
