Metadata-Version: 2.4
Name: ImagePRO-Python
Version: 1.2.1
Summary: Professional & modular image processing library with OpenCV, MediaPipe, and YOLO integration.
Author-email: Parsa Safaie <parsasafaie.2568@proton.me>
License: MIT
Project-URL: Homepage, https://github.com/parsasafaie/ImagePRO
Project-URL: Repository, https://github.com/parsasafaie/ImagePRO.git
Project-URL: Documentation, https://github.com/parsasafaie/ImagePRO#readme
Project-URL: Issues, https://github.com/parsasafaie/ImagePRO/issues
Keywords: opencv,mediapipe,computer-vision,face,pose,yolo,image-processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.1.0,>=1.24
Requires-Dist: opencv-python<5.0,>=4.8
Requires-Dist: matplotlib<4.0,>=3.7
Provides-Extra: yolo
Requires-Dist: ultralytics<9.0,>=8.2; extra == "yolo"
Provides-Extra: mediapipe
Requires-Dist: mediapipe<=0.10.11,>=0.10.0; extra == "mediapipe"
Provides-Extra: insightface
Requires-Dist: insightface<0.8,>=0.7; extra == "insightface"
Requires-Dist: onnxruntime<2.0,>=1.16; extra == "insightface"
Provides-Extra: full
Requires-Dist: mediapipe<=0.10.11,>=0.10.0; extra == "full"
Requires-Dist: ultralytics<9.0,>=8.2; extra == "full"
Requires-Dist: insightface<0.8,>=0.7; extra == "full"
Requires-Dist: onnxruntime<2.0,>=1.16; extra == "full"
Dynamic: license-file

# ImagePRO

> **Professional & Modular Image Processing Library in Python**

**ImagePRO** is a clean, modular, and easy-to-use Python library for image processing tasks, built with OpenCV, MediaPipe, YOLO, and InsightFace. Designed to be extensible for developers, ImagePRO provides a consistent API across all modules with comprehensive error handling and professional-grade documentation.

Whether you're working on computer vision pipelines, preprocessing images for AI models, or simply automating batch image edits — **ImagePRO** gives you powerful tools with minimal effort.

## ✨ Features

### **Image I/O & Management**
- Flexible input/output handling (file paths or numpy arrays)
- Batch processing capabilities
- Multiple format support (JPEG, PNG, CSV, etc.)

### **Pre-processing & Enhancement**
- **Basic Operations**: Resize, crop, rotate (90°, 180°, 270°, custom angles), grayscale conversion
- **Filtering**: Blur filters (average, Gaussian, median, bilateral), sharpening filters (Laplacian, Unsharp Masking)
- **Enhancement**: Contrast enhancement (CLAHE, GHE, stretching)
- **Dataset Generation**: Automated image capture with preprocessing pipeline

### **Human Analysis**
- **Face Analysis**: 468-point mesh, head pose estimation, eye status detection, face comparison, face cropping
- **Body Analysis**: Pose estimation, hand tracking (21 landmarks)
- **Real-time Processing**: Live webcam analysis for all modules

### **Object Detection**
- **YOLO Integration**: Multiple accuracy levels (nano to extra-large)
- **Flexible Models**: Pre-trained or custom model support
- **Batch Processing**: Efficient handling of multiple images

## 🚀 Installation

### From PyPI
```bash
pip install ImagePRO-Python
```

### From Source
```bash
git clone https://github.com/parsasafaie/ImagePRO.git
cd ImagePRO

python -m venv .venv

source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows

# Base dependencies
pip install -r requirements/base.txt

# Optional dependencies
# For YOLO object detection
pip install -r requirements/yolo.txt

# For MediaPipe human analysis
pip install -r requirements/mediapipe.txt

# For InsightFace advanced face analysis
pip install -r requirements/insightface.txt

# Or install everything
pip install -r requirements/full.txt
```

See the [Directory Structure](/PROJECT_STRUCTURE.md#directory-structure) section in [PROJECT_STRUCTURE.md](/PROJECT_STRUCTURE.md) for details on which modules need which requirements.

## 📖 Quick Start

```python
from ImagePRO.pre_processing.blur import apply_average_blur
from ImagePRO.human_analysis.face_analysis.face_mesh_analysis import analyze_face_mesh
from ImagePRO.human_analysis.body_analysis.body_pose_estimation import detect_body_pose
from ImagePRO.object_analysis.object_detection import detect_objects
from ImagePRO.utils.image import Image

# Load an image
image = Image.from_path("person_and_objects.jpg")
# Or from numpy array: image = Image.from_array(np_array)

# Apply average blur
blur_result = apply_average_blur(image=image)
blur_result.save_as_img("blurred_output.jpg")

# Analyze face mesh (468 landmarks)
face_mesh_result = analyze_face_mesh(image=image)
print(f"Detected {len(face_mesh_result.data)} face landmarks")
face_mesh_result.save_as_csv("face_landmarks.csv")

# Detect body pose (33 landmarks)
body_pose_result = detect_body_pose(image=image)
print(f"Body pose data: {body_pose_result.data}")

# Detect objects with YOLO
object_detection_result = detect_objects(
    image=image,
    accuracy_level=3,  # 1=nano, 2=small, 3=medium, 4=large, 5=extra-large
    confidence=0.5
)
print(f"Detected {len(object_detection_result.data)} objects")
object_detection_result.save_as_img("detections.jpg")
```

> **Note**: These are basic examples. Each module contains many more functions with extensive customization options. Explore the module-specific README files for detailed documentation.

## 📚 Documentation

Each module includes comprehensive documentation with detailed examples:

- **[Pre-processing](src/ImagePRO/pre_processing/README.md)**: Image manipulation, filtering, and enhancement
- **[Human Analysis](src/ImagePRO/human_analysis/README.md)**: Face and body analysis tools
  - [Face Analysis](src/ImagePRO/human_analysis/face_analysis/README.md): Face mesh, pose estimation, eye status, comparison
  - [Body Analysis](src/ImagePRO/human_analysis/body_analysis/README.md): Body pose and hand tracking
- **[Object Analysis](src/ImagePRO/object_analysis/README.md)**: YOLO-based object detection
- **[Utils](src/ImagePRO/utils/README.md)**: Shared utilities and I/O handling

For detailed project structure and development guidelines, see [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md).

## 🏗️ Architecture

ImagePRO is built with a modular architecture designed for extensibility and maintainability:

- **Clean Separation of Concerns**: Each module handles a specific domain
- **Consistent API Patterns**: All functions follow the same input/output conventions
- **Shared Utilities**: Common `Image` and `Result` classes for unified I/O
- **Professional Error Handling**: Comprehensive validation with clear error messages
- **Type Safety**: Full type hints throughout the codebase
- **Documentation**: Google-style docstrings for all functions

### Key Design Principles
- **Immutable Design**: Image objects are immutable, operations return new instances
- **Functional Style**: Stateless functions that can be easily composed
- **Result Objects**: Unified return type containing image, data, and metadata
- **Keyword Arguments**: All optional parameters use keyword-only syntax

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Setup
1. Fork the repository
2. Create a virtual environment: `python -m venv .venv`
3. Install dependencies: `pip install -r requirements/full.txt`
4. Follow the coding standards outlined in [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
5. Add tests for new features
6. Update documentation as needed

### Reporting Issues
If you encounter any bugs or have feature requests, please open an issue on the GitHub repository with:
- Description of the problem or feature request
- Steps to reproduce (for bugs)
- Expected vs. actual behavior
- Environment details (OS, Python version, etc.)

## 📄 License 
This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.
