Metadata-Version: 2.4
Name: photo_ops
Version: 0.0.4
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Summary: High-Performance Image Intelligence for Lakhs of Images. Hint: This is a pre-released version, original will be available soon. Release date will be announced by end of May. Submit your comments via form.
Author-email: Dhileep <sdhileep075@gmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Feedback, https://forms.gle/CBhJVP3XdbZh1B2J7
Project-URL: Homepage, https://crasywriters.blogspot.com/p/photoops.html

# photo_ops 📸

**High-Performance Image Intelligence for Large-Scale Data Processing**

`photo_ops` is an enterprise-grade image processing suite engineered in **Rust** for maximum throughput and low-latency performance. It provides a seamless **Python API** for intelligent structural recognition, orientation correction, and subject-aware cropping.

---

## 🚀 Key Features

*   **Intelligent Routing**: Automatically distinguishes between Signatures and Subjects (faces), routing them to specialized processing pipelines.
*   **Subject-Aware Cropping**: Beyond simple center-crops; uses structural intelligence to perfectly frame faces or signature ink.
*   **Production Reliability**: Features atomic file operations, automated error handling, and robust Excel/TSV audit trails.
*   **High Throughput**: Bypasses the Python GIL using a multi-threaded Rust core, enabling processing of lakhs of images with zero performance degradation.

---

## 🛠 Enterprise APIs

### **Signature & Document Intelligence**
*   **`ip.sign_fix(in, out, w=None, h=None)`**: Detect and crop signatures. `w` and `h` are **optional**; if omitted, it returns the original tight crop.
    ```python
    ip.sign_fix("scan.jpg", "sign.jpg", w=400, h=200) # With resize
    ip.sign_fix("scan.jpg", "sign_orig.jpg")         # Original size crop
    ```
*   **`ip.signcheck(path)`**: Returns `True` if image is a signature.
    ```python
    if ip.signcheck("file.jpg"): print("Signature detected")
    ```
*   **`ip.enhance_signature(in, out)`**: Detailing/Binarization.
    ```python
    ip.enhance_signature("ink.jpg", "clean.jpg")
    ```

### **Portrait & Subject Management**
*   **`ip.sub_fix(in, out, w=None, h=None)`**: Passport framing. `w` and `h` are **optional**.
    ```python
    ip.sub_fix("photo.jpg", "passport.jpg", w=300, h=400)
    ```
*   **`ip.portrait(in, out, blur_bg=15)`**: Portrait mode with background blur.
    ```python
    ip.portrait("subject.jpg", "portrait.jpg", blur_bg=25)
    ```
*   **`ip.fix_turn(in, out)`**: Auto-orientation correction.
    ```python
    ip.fix_turn("raw.jpg", "oriented.jpg")
    ```
*   **`ip.match_turn(in, ref, out)`**: Synchronize rotation.
    ```python
    ip.match_turn("input.jpg", "reference.jpg", "output.jpg")
    ```

### **Core Image Operations**
*   **`ip.gray(in, out)`**: Grayscale conversion.
    ```python
    ip.gray("color.jpg", "gray.jpg")
    ```
*   **`ip.resize(in, out, w, h)`**: Precise resizing.
    ```python
    ip.resize("large.png", "small.png", 800, 600)
    ```
*   **`ip.scale(in, out, factor)`**: Proportional scaling.
    ```python
    ip.scale("orig.jpg", "half.jpg", 0.5)
    ```
*   **`ip.flip(in, out, mode)`**: Mirroring ('horizontal'/'vertical').
    ```python
    ip.flip("left.jpg", "right.jpg", "horizontal")
    ```
*   **`ip.info(path)`**: Metadata extraction.
    ```python
    data = ip.info("image.jpg") # returns {'width', 'height', ...}
    ```

### **Visual Effects & Adjustments**
*   **`ip.remove_bg(in, out)`**: Background removal (PNG).
    ```python
    ip.remove_bg("subject.jpg", "transparent.png")
    ```
*   **`ip.edge_art(in, out)`**: Sketch effect.
    ```python
    ip.edge_art("photo.jpg", "sketch.jpg")
    ```
*   **`ip.brightness(in, out, val)`**: Light adjustment.
    ```python
    ip.brightness("dark.jpg", "lit.jpg", 30)
    ```
*   **`ip.saturation(in, out, val)`**: Color depth.
    ```python
    ip.saturation("dull.jpg", "vibrant.jpg", 1.5)
    ```
*   **`ip.blur(in, out, ksize)`**: Gaussian blur.
    ```python
    ip.blur("sharp.jpg", "soft.jpg", 11)
    ```
*   **`ip.sharpen(in, out)`**: Image detailing.
    ```python
    ip.sharpen("soft.jpg", "crisp.jpg")
    ```

### **Automated Batch Processing**
*   **`ip.process(config)`**: High-volume orchestration.
    *   **Automatic Sorting**: Groups output into `success`, `subjects`, and `failed` directories.
    *   **Automated Auditing**: Generates `log_success.xlsx` and `log_failed.xlsx` automatically.

---

## 📈 Example Usage

## 🚀 Code Examples by Activity

### **Orientation Correction**
Automatically fix or synchronize image rotations.
```python
import photo_ops as ip

# Full intelligence-based auto-rotation
ip.fix_turn("raw_scan.jpg", "fixed.jpg")

# Synchronize orientation of a batch to match a reference image
ip.match_turn("input.jpg", "reference.jpg", "output.jpg")
```

### **Signature Processing**
Extract and clean ink from scanned documents.
```python
# Intelligent signature extraction (Auto-crop + Resize)
ip.sign_fix("A4_scan.jpg", "signature.jpg", width=400, height=200)

# Remove shadows and noise for professional detailing
ip.enhance_signature("raw_ink.jpg", "detailing.jpg")
```

### **Portrait & Passport Processing**
Subject-aware framing and stylized effects.
```python
# Automated passport-style framing (Centers face)
ip.sub_fix("vacation.jpg", "passport.jpg", width=300, height=400)

# Professional portrait mode (Sharp face, blurred background)
ip.portrait("subject.jpg", "portrait_mode.jpg", blur_bg=15)
```

### **Color & Visual Enhancements**
Pixel-level adjustments and filters.
```python
# High-speed grayscale
ip.gray("color.jpg", "gray.jpg")

# Adjust lighting and color depth
ip.brightness("dim_photo.jpg", "bright.jpg", value=30)
ip.saturation("dull.jpg", "vibrant.jpg", value=1.5)

# Artistic edge softening
ip.edge_art("nature.jpg", "art.jpg")
```

### **Enterprise Batch Orchestration**
Process thousands of mixed images with intelligent routing and automated Excel auditing.
```python
# Complex task configuration
task = {
    "input": "incoming_scans/", 
    "output": "cleared_database/",
    "ops": ["sign_fix", "gray", "log"], 
    "width": 400, "height": 400,  #optional support
    "stats": True,                # Interactive terminal dashboard
    "log_file": "audit_report.xlsx" 
}

# The engine routes to 'success', 'subjects', or 'failed' subfolders automatically
ip.process(task)
```

---

## 📊 Competitive Performance
*Benchmarked on 100k+ images (1080p mixed formats) on an 8-core CPU:*

| Capability | photo_ops (Rust) | Pillow (Python) | OpenCV (Python) |
| :--- | :--- | :--- | :--- |
| **Throughput** | **800+ images/min** | ~150 images/min | ~300 images/min |
| **Parallelism** | **Rayon (Native Threads)** | Multiprocessing | Single-threaded (GIL) |
| **Smart Vision** | **Built-in Seeta/LGC** | None | Limited (Haar) |

---

## 📦 Installation
```bash
pip install photo_ops
```

---

## 🏗 Support & Feedback
Submit your professional feedback here: **[Google Form](https://forms.gle/CBhJVP3XdbZh1B2J7)**

*Developed for high-throughput image intelligence and industrial-scale data pipelines.*

