ImagePRO-Python 1.2.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

ImagePRO/pre_processing/dataset_generator.py

@@ -45,9 +45,12 @@ def capture_bulk_pictures(
 ) -> None:
     """Generate a dataset by capturing faces from webcam.
 
-    Captures frames and saves preprocessed face images.
+    Captures frames from the webcam, detects faces, applies optional preprocessing,
+    and saves cropped face images to disk. This function is useful for creating
+    face recognition datasets with data augmentation.
+
     Processing pipeline (if enabled):
-    median blur → laplacian sharpen → grayscale → resize → random rotate
+    average blur → laplacian sharpen → grayscale → resize → random rotate
 
     Args:
         folder_path: Base directory for dataset.
@@ -80,7 +83,7 @@ def capture_bulk_pictures(
         FileExistsError: If output folder exists
         RuntimeError: If camera access fails
     """
-    # Validate numeric parameters
+    # Validate numeric parameters to ensure safe operation
     if not isinstance(num_images, int) or num_images <= 0:
         raise ValueError("'num_images' must be a positive integer")
 
@@ -93,20 +96,23 @@ def capture_bulk_pictures(
     if not isinstance(delay, (int, float)) or delay < 0:
         raise ValueError("'delay' must be a non-negative number")
 
-    # Setup output directory
+    # Setup output directory structure
     base_dir = Path(folder_path)
     face_folder = base_dir / str(face_id)
 
+    # Create output folder (fail if exists to prevent accidental overwrites)
     try:
         face_folder.mkdir(parents=True, exist_ok=False)
     except FileExistsError as e:
         raise FileExistsError(f"Output folder already exists: {face_folder}") from e
 
-    # Initialize camera and face detector
+    # Initialize camera capture
     cap = cv2.VideoCapture(camera_index)
     if not cap.isOpened():
         raise RuntimeError(f"Cannot access camera (index={camera_index})")
 
+    # Initialize MediaPipe face mesh detector for face detection
+    # Using face_mesh instead of face_detection for better accuracy
     face_mesh = mp.solutions.face_mesh.FaceMesh(
         max_num_faces=1,
         min_detection_confidence=min_confidence,
@@ -123,36 +129,40 @@ def capture_bulk_pictures(
                 print("Failed to capture frame, skipping...")
                 continue
 
-            # Apply preprocessing pipeline
+            # Apply preprocessing pipeline in sequence
+            # Each step transforms the image and passes it to the next step
             processed = frame
 
             if apply_blur:
-                # Reduce noise while keeping facial features
+                # Reduce noise while preserving facial features
                 processed = blur.apply_average_blur(
                     image=Image.from_array(processed),
                     filter_size=3
                 ).image
 
             if apply_sharpen:
-                # Enhance edges with gentle sharpening
+                # Enhance edges with gentle sharpening for better feature detection
                 processed = sharpen.apply_laplacian_sharpening(
                     image=Image.from_array(processed),
                     coefficient=1.0
                 ).image
 
             if apply_grayscale:
+                # Convert to single-channel for reduced storage and faster processing
                 processed = grayscale.convert_to_grayscale(
                     image=Image.from_array(processed)
                 ).image
 
             if apply_resize is not False:
+                # Resize to consistent dimensions (e.g., 224x224 for ML models)
                 processed = resize.resize_image(
                     image=Image.from_array(processed),
                     new_size=apply_resize
                 ).image
 
             if apply_rotate:
-                # Apply random rotation with scaling
+                # Apply random rotation with scaling for data augmentation
+                # Rotation range: -45° to +45° with random scale factors
                 angle = float(random.randint(-45, 45))
                 scale = random.choice([1.0, 1.1, 1.2, 1.3])
                 processed = rotate.rotate_image_custom(
@@ -161,11 +171,12 @@ def capture_bulk_pictures(
                     scale=scale
                 ).image
 
-            # Save processed face image
+            # Detect and crop face from processed frame
             filename = f"{start_index + saved_count:04d}.jpg"
             output_path = face_folder / filename
 
             try:
+                # Detect face and crop to face region only
                 result = detect_faces(
                     image=Image.from_array(processed),
                     max_faces=1,
@@ -173,18 +184,20 @@ def capture_bulk_pictures(
                     face_mesh_obj=face_mesh
                 )
 
+                # Save cropped face image
                 result.save_as_img(str(output_path))
                 saved_count += 1
 
+                # Add delay between captures to allow subject movement
                 if delay > 0:
                     time.sleep(delay)
 
             except ValueError:
-                # Skip frames with no detected faces
+                # Skip frames with no detected faces (silent failure)
                 continue
 
     finally:
-        # Clean up resources
+        # Clean up resources: release camera and close OpenCV windows
         cap.release()
         cv2.destroyAllWindows()
 

ImagePRO/utils/result.py

@@ -144,7 +144,22 @@ class Result:
         return self
 
 def flatten_rows(data):
-    """Flatten any nested lists/tuples into rows suitable for CSV writing."""
+    """
+    Flatten nested lists/tuples into rows suitable for CSV writing.
+    
+    Recursively processes nested data structures to create a flat list of rows
+    that can be written to a CSV file. Handles mixed nesting levels gracefully.
+    
+    Args:
+        data: Nested list/tuple structure containing data to flatten.
+        
+    Returns:
+        list[list[Any]]: Flattened list of rows, where each row is a list of values.
+        
+    Example:
+        >>> flatten_rows([[1, 2], [3, [4, 5]]])
+        [[1, 2], [3, 4, 5]]
+    """
     rows = []
     for item in data:
         if isinstance(item, (list, tuple)):

imagepro_python-1.2.1.dist-info/METADATA

@@ -0,0 +1,200 @@
+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.

{imagepro_python-1.2.0.dist-info → imagepro_python-1.2.1.dist-info}/RECORD

@@ -15,7 +15,7 @@ ImagePRO/pre_processing/__init__.py,sha256=nXUhE8RnDyW7T93fKsSDPfqzGHIW50OvgQvzn
 ImagePRO/pre_processing/blur.py,sha256=zPWUKLEoKiL6kYwnZOtGRWBHM-dgEQ8WWdDt8_wGc0s,7961
 ImagePRO/pre_processing/contrast.py,sha256=XG69VsX3EKWIPDcQYm4D9qT7sA_BSP-sppSAa8qRUhA,5247
 ImagePRO/pre_processing/crop.py,sha256=p0esuZcn4-YsqcniDUmsVfPoWasxVH1OqzNBra8Pw4M,2442
-ImagePRO/pre_processing/dataset_generator.py,sha256=Vf21SwzsKRBHespvAY6N7Ozq_G0GrL7T5sAk0FOyEk0,6625
+ImagePRO/pre_processing/dataset_generator.py,sha256=ekd_TnyflWKjJ6sYCiWc3vN2Q14cKiwZ1InOCslxoFM,7653
 ImagePRO/pre_processing/grayscale.py,sha256=MRCsFRIaL45sYVHzhuNyZBXsP7PF-yorn0Wt7xONvpY,1781
 ImagePRO/pre_processing/histogram.py,sha256=t1ykGUwB9ZbvO6J3bGPh4fDvrk4AJua1dN2BWzHIRIQ,2888
 ImagePRO/pre_processing/resize.py,sha256=GH3ObPe67ypPQG3a7ncrNR5WNDqGibXebAiuRXr6L10,1760
@@ -23,9 +23,9 @@ ImagePRO/pre_processing/rotate.py,sha256=wqV2Qm7mIyvKTSFdwzr1tNAGnMG7rl5M3BRqC5m
 ImagePRO/pre_processing/sharpen.py,sha256=C5AOxQNBL80JenkztlyRBV7yuCHqxG5dTGbRhtVRT9M,3544
 ImagePRO/utils/__init__.py,sha256=McVd-o9KtKOpAVYbLi19KxsatPPFFF-Qbt0gdgY3Ln8,170
 ImagePRO/utils/image.py,sha256=x93cBNycNOgET20a__TxZ9ZQo_2G84uB7QjXjBo9f8M,3973
-ImagePRO/utils/result.py,sha256=DAFaFZ5jZZ7C2YrhRs6h2PAei6Mbv1Mu8xX_2NQ7c6Y,5605
-imagepro_python-1.2.0.dist-info/licenses/LICENSE,sha256=sehkHN7dbe5umrINZJyJjIf9VTemZSgTfJlq6iIsbJQ,1069
-imagepro_python-1.2.0.dist-info/METADATA,sha256=qxax-bzhfBbcMHNP4nbRKHBVMJO2MSkTDyIQiWcmMGA,2095
-imagepro_python-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-imagepro_python-1.2.0.dist-info/top_level.txt,sha256=UOuPzsoWrVKXgUupOSI96shJ6wE8Fhz-8bm8oMlLC3s,9
-imagepro_python-1.2.0.dist-info/RECORD,,
+ImagePRO/utils/result.py,sha256=rGZX0FJ-dpA4v_m_GUO6ni0kCfcNJRnOjztbyRX9d88,6065
+imagepro_python-1.2.1.dist-info/licenses/LICENSE,sha256=sehkHN7dbe5umrINZJyJjIf9VTemZSgTfJlq6iIsbJQ,1069
+imagepro_python-1.2.1.dist-info/METADATA,sha256=KVaRtAoER1Ss2HS1R8w6YrIrfwt8zH5bw5u_29sMjGA,8513
+imagepro_python-1.2.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+imagepro_python-1.2.1.dist-info/top_level.txt,sha256=UOuPzsoWrVKXgUupOSI96shJ6wE8Fhz-8bm8oMlLC3s,9
+imagepro_python-1.2.1.dist-info/RECORD,,

{imagepro_python-1.2.0.dist-info → imagepro_python-1.2.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (82.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

imagepro_python-1.2.0.dist-info/METADATA

@@ -1,44 +0,0 @@
-Metadata-Version: 2.4
-Name: ImagePRO-Python
-Version: 1.2.0
-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: Programming Language :: Python :: 3.13
-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<3.0,>=1.24
-Requires-Dist: opencv-python<6.0,>=4.8
-Requires-Dist: matplotlib<4.0,>=3.7
-Provides-Extra: yolo
-Requires-Dist: ultralytics<10.0,>=8.2; extra == "yolo"
-Provides-Extra: mediapipe
-Requires-Dist: mediapipe<1.0,>=0.10; extra == "mediapipe"
-Provides-Extra: insightface
-Requires-Dist: insightface<1.0,>=0.7; extra == "insightface"
-Requires-Dist: onnxruntime<3.0,>=1.16; extra == "insightface"
-Provides-Extra: full
-Requires-Dist: mediapipe<1.0,>=0.10; extra == "full"
-Requires-Dist: ultralytics<10.0,>=8.2; extra == "full"
-Requires-Dist: insightface<1.0,>=0.7; extra == "full"
-Requires-Dist: onnxruntime<3.0,>=1.16; extra == "full"
-Dynamic: license-file