ImagePRO-Python 0.5.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

ImagePRO/pre_processing/dataset_generator.py

@@ -1,21 +1,15 @@
-import sys
-import time
+from __future__ import annotations
+
 import random
+import time
 from pathlib import Path
 
 import cv2
 import mediapipe as mp
 
-# Add parent directory to sys.path for local imports
-parent_dir = Path(__file__).resolve().parent.parent
-sys.path.append(str(parent_dir))
-
-from human_analysis.face_analysis.face_detection import detect_faces
-from blur import apply_median_blur
-from sharpen import apply_laplacian_sharpening
-from rotate import rotate_image_custom
-from grayscale import convert_to_grayscale
-from resize import resize_image
+from ImagePRO.human_analysis.face_analysis.face_detection import detect_faces
+from ImagePRO.pre_processing import blur, grayscale, rotate, sharpen, resize
+from ImagePRO.utils.image import Image
 
 # Constants
 DEFAULT_NUM_IMAGES = 200
@@ -29,6 +23,7 @@ DEFAULT_FACE_ID = "unknown"
 def capture_bulk_pictures(
     folder_path: str | Path,
     face_id: str | int = DEFAULT_FACE_ID,
+    *,
     num_images: int = DEFAULT_NUM_IMAGES,
     start_index: int = DEFAULT_START_INDEX,
     min_confidence: float = DEFAULT_MIN_CONFIDENCE,
@@ -38,133 +33,150 @@ def capture_bulk_pictures(
     apply_sharpen: bool = False,
     apply_rotate: bool = False,
     apply_resize: tuple = False,
-    delay: float = DEFAULT_DELAY,
+    delay: float = DEFAULT_DELAY
 ) -> None:
-    """
-    Capture frames from webcam and save cropped face images, with optional preprocessing.
+    """Generate a dataset by capturing faces from webcam.
 
-    Processing order (if enabled):
+    Captures frames and saves preprocessed face images.
+    Processing pipeline (if enabled):
     median blur → laplacian sharpen → grayscale → resize → random rotate
 
-    Parameters
-    ----------
-    folder_path : str | Path
-        Base directory where the face-id folder will be created.
-    face_id : str | int
-        Subfolder name (e.g., user id). A new folder "<folder_path>/<face_id>" will be created.
-    num_images : int, default=200
-        Number of frames to capture/save.
-    start_index : int, default=0
-        Starting index for saved filenames (zero-padded).
-    min_confidence : float, default=0.7
-        Detection confidence for MediaPipe FaceMesh.
-    camera_index : int, default=0
-        OpenCV camera index.
-    apply_blur : bool, default=False
-        Apply median blur (filter_size=3) before other steps.
-    apply_grayscale : bool, default=False
-        Convert frame to single-channel grayscale.
-    apply_sharpen : bool, default=False
-        Apply Laplacian-based sharpening (coefficient=1.0).
-    apply_rotate : bool, default=False
-        Apply a random rotation in [-45°, +45°] with random scale {1.0, 1.1, 1.2, 1.3}.
-    apply_resize : tuple[int, int] | None, default=None
-        If provided, resize to (width, height) before rotation.
-    delay : float, default=0.1
-        Delay between each capture in seconds.
-
-    Raises
-    ------
-    ValueError
-        If arguments are invalid.
-    FileExistsError
-        If the destination folder already exists.
-    RuntimeError
-        If the webcam cannot be opened.
+    Args:
+        folder_path: Base directory for dataset.
+        face_id: Subject identifier, creates folder "<base_dir>/<face_id>".
+            Default: "unknown"
+        num_images: Number of images to capture.
+            Default: 200
+        start_index: Starting number for filenames.
+            Default: 0
+        min_confidence: Face detection confidence threshold.
+            Default: 0.7
+        camera_index: OpenCV camera device index.
+            Default: 0
+        apply_blur: Apply median blur (size=3).
+            Default: False
+        apply_grayscale: Convert to single-channel.
+            Default: False
+        apply_sharpen: Apply Laplacian (coef=1.0).
+            Default: False
+        apply_rotate: Random rotation [-45°,45°].
+            Default: False
+        apply_resize: Optional (width,height).
+            Default: False (no resize)
+        delay: Time between captures (seconds).
+            Default: 0.1
+
+    Raises:
+        TypeError: If input types are invalid
+        ValueError: If numeric values are out of range
+        FileExistsError: If output folder exists
+        RuntimeError: If camera access fails
     """
+    # Validate numeric parameters
     if not isinstance(num_images, int) or num_images <= 0:
-        raise ValueError("'num_images' must be a positive integer.")
+        raise ValueError("'num_images' must be a positive integer")
+
     if not isinstance(start_index, int) or start_index < 0:
-        raise ValueError("'start_index' must be a non-negative integer.")
+        raise ValueError("'start_index' must be a non-negative integer")
+
     if not isinstance(min_confidence, (int, float)) or not (0 <= min_confidence <= 1):
-        raise ValueError("'min_confidence' must be between 0 and 1.")
+        raise ValueError("'min_confidence' must be between 0 and 1")
+
     if not isinstance(delay, (int, float)) or delay < 0:
-        raise ValueError("'delay' must be a non-negative number.")
+        raise ValueError("'delay' must be a non-negative number")
 
+    # Setup output directory
     base_dir = Path(folder_path)
     face_folder = base_dir / str(face_id)
 
-    # Create destination folder (fail if exists to avoid accidental overwrite)
     try:
         face_folder.mkdir(parents=True, exist_ok=False)
     except FileExistsError as e:
-        raise FileExistsError(f"Destination already exists: {face_folder}") from e
+        raise FileExistsError(f"Output folder already exists: {face_folder}") from e
 
-    # Open webcam
+    # Initialize camera and face detector
     cap = cv2.VideoCapture(camera_index)
     if not cap.isOpened():
-        raise RuntimeError(f"Failed to open webcam (index={camera_index}).")
+        raise RuntimeError(f"Cannot access camera (index={camera_index})")
 
-    # Initialize FaceMesh for live stream (tracking mode)
     face_mesh = mp.solutions.face_mesh.FaceMesh(
         max_num_faces=1,
         min_detection_confidence=min_confidence,
         refine_landmarks=True,
-        static_image_mode=False,
+        static_image_mode=False
     )
 
-    saved = 0
+    saved_count = 0
     try:
-        while saved < num_images:
-            ok, frame = cap.read()
-            if not ok:
-                print("Skipping empty frame.")
+        while saved_count < num_images:
+            # Capture frame
+            success, frame = cap.read()
+            if not success:
+                print("Failed to capture frame, skipping...")
                 continue
 
-            # Optional preprocessing steps
-            proc = frame
+            # Apply preprocessing pipeline
+            processed = frame
 
             if apply_blur:
-                # Small kernel to keep facial details while reducing salt-and-pepper noise
-                proc = apply_median_blur(src_np_image=proc, filter_size=3)
+                # Reduce noise while keeping facial features
+                processed = blur.apply_average_blur(
+                    image=Image.from_array(processed),
+                    filter_size=3
+                ).image
 
             if apply_sharpen:
-                # Gentle sharpening; adjust coefficient if needed
-                proc = apply_laplacian_sharpening(src_np_image=proc, coefficient=1.0)
+                # Enhance edges with gentle sharpening
+                processed = sharpen.apply_laplacian_sharpening(
+                    image=Image.from_array(processed),
+                    coefficient=1.0
+                ).image
 
             if apply_grayscale:
-                proc = convert_to_grayscale(src_np_image=proc)
+                processed = grayscale.convert_to_grayscale(
+                    image=Image.from_array(processed)
+                ).image
 
             if apply_resize is not False:
-                proc = resize_image(new_size=apply_resize, src_np_image=proc)
+                processed = resize.resize_image(
+                    image=Image.from_array(processed),
+                    new_size=apply_resize
+                ).image
 
             if apply_rotate:
+                # Apply random rotation with scaling
                 angle = float(random.randint(-45, 45))
                 scale = random.choice([1.0, 1.1, 1.2, 1.3])
-                proc = rotate_image_custom(src_np_image=proc, angle=angle, scale=scale)
+                processed = rotate.rotate_image_custom(
+                    image=Image.from_array(processed),
+                    angle=angle,
+                    scale=scale
+                ).image
 
-            # Zero-padded filenames for better ordering
-            filename = f"{start_index + saved:04d}.jpg"
-            out_path = face_folder / filename
+            # Save processed face image
+            filename = f"{start_index + saved_count:04d}.jpg"
+            output_path = face_folder / filename
 
             try:
-                # Save cropped face image via standardized detect_faces
-                detect_faces(
+                result = detect_faces(
+                    image=Image.from_array(processed),
                     max_faces=1,
                     min_confidence=min_confidence,
-                    src_np_image=proc,
-                    output_image_path=str(out_path),
-                    face_mesh_obj=face_mesh,
+                    face_mesh_obj=face_mesh
                 )
-                saved += 1
+
+                result.save_as_img(str(output_path))
+                saved_count += 1
 
                 if delay > 0:
                     time.sleep(delay)
 
             except ValueError:
-                # No face detected; skip this frame
+                # Skip frames with no detected faces
                 continue
+
     finally:
+        # Clean up resources
         cap.release()
         cv2.destroyAllWindows()
 

ImagePRO/pre_processing/grayscale.py

@@ -1,50 +1,50 @@
-import sys
-from pathlib import Path
-import cv2
-import numpy as np
+from __future__ import annotations
 
-# Add parent directory to sys.path for custom module imports
-parent_dir = Path(__file__).resolve().parent.parent
-sys.path.append(str(parent_dir))
+import cv2
 
-from utils.io_handler import IOHandler
+from ImagePRO.utils.image import Image
+from ImagePRO.utils.result import Result
 
 
-def convert_to_grayscale(
-    src_image_path: str | None = None,
-    src_np_image=None,
-    output_image_path: str | None = None
-) -> np.ndarray:
+def convert_to_grayscale(image: Image) -> Result:
     """
     Convert an image to grayscale.
 
-    Parameters
-    ----------
-    src_image_path : str | None, optional
-        Path to input image.
-    src_np_image : np.ndarray | None, optional
-        Preloaded BGR image array.
-    output_image_path : str | None, optional
-        If provided, save the grayscale image.
-
-    Returns
-    -------
-    np.ndarray
-        Grayscale image.
-
-    Raises
-    ------
-    TypeError
-        If input types are invalid.
-    FileNotFoundError
-        If image path does not exist.
-    IOError
-        If saving the image fails.
+    Converts BGR or RGB image to single-channel grayscale using OpenCV.
+    For BGR images (default), uses standard ITU-R BT.601 conversion.
+    For RGB images, automatically handles colorspace conversion.
+
+    Args:
+        image (Image):
+            Input image to convert. Must be BGR or RGB format.
+
+    Returns:
+        Result: Result object with converted grayscale image.
+            - image (np.ndarray): Single-channel grayscale image
+            - data (None): No additional data
+            - meta (dict): Contains source object and operation info
+
+    Raises:
+        TypeError: If image is not an Image instance
+        ValueError: If image colorspace is already GRAY
     """
-    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
-    grayscale = cv2.cvtColor(np_image, cv2.COLOR_BGR2GRAY)
-    
-    if output_image_path:
-        print(IOHandler.save_image(grayscale, output_image_path))
-    
-    return grayscale
+    if not isinstance(image, Image):
+        raise TypeError("'image' must be an Image instance.")
+
+    if image.colorspace == "GRAY":
+        raise ValueError("Image is already in grayscale format.")
+
+    # Convert based on source colorspace
+    if image.colorspace == "RGB":
+        grayscale = cv2.cvtColor(image._data, cv2.COLOR_RGB2GRAY)
+    else:  # BGR is default
+        grayscale = cv2.cvtColor(image._data, cv2.COLOR_BGR2GRAY)
+
+    return Result(
+        image=grayscale,
+        data=None,
+        meta={
+            "source": image,
+            "operation": "convert_to_grayscale"
+        }
+    )

ImagePRO/pre_processing/resize.py

@@ -1,62 +1,54 @@
-import sys
-from pathlib import Path
-import cv2
-import numpy as np
+from __future__ import annotations
 
-# Add parent directory to sys.path for custom module imports
-parent_dir = Path(__file__).resolve().parent.parent
-sys.path.append(str(parent_dir))
+import cv2
 
-from utils.io_handler import IOHandler
+from ImagePRO.utils.image import Image
+from ImagePRO.utils.result import Result
 
 
 def resize_image(
-    new_size: tuple[int, int],
-    src_image_path: str | None = None,
-    src_np_image=None,
-    output_image_path: str | None = None
-) -> np.ndarray:
-    """
-    Resize an image to new dimensions.
-
-    Parameters
-    ----------
-    new_size : tuple[int, int]
-        New image size as (width, height).
-    src_image_path : str | None, optional
-        Path to input image.
-    src_np_image : np.ndarray | None, optional
-        Preloaded BGR image array.
-    output_image_path : str | None, optional
-        If provided, save the resized image.
-
-    Returns
-    -------
-    np.ndarray
-        Resized image.
-
-    Raises
-    ------
-    ValueError
-        If new_size is invalid.
-    TypeError
-        If input types are invalid.
-    FileNotFoundError
-        If image path does not exist.
-    IOError
-        If saving the image fails.
+    image: Image,
+    *,
+    new_size: tuple[int, int]
+) -> Result:
+    """Resize an image to specified dimensions.
+
+    Changes image size while maintaining aspect ratio.
+    Uses bilinear interpolation for smooth resizing.
+
+    Args:
+        image: Input image to resize.
+        new_size: Target size as (width, height) in pixels.
+            Both dimensions must be positive integers.
+
+    Returns:
+        Result object with resized image and metadata:
+        - image: Resized image array
+        - data: None
+        - meta: Operation info and new size used
+
+    Raises:
+        TypeError: If image is not an Image instance
+        ValueError: If new_size is not valid (tuple of 2 positive ints)
     """
+    if not isinstance(image, Image):
+        raise TypeError("'image' must be an Image instance")
+
     if (
         not isinstance(new_size, tuple)
         or len(new_size) != 2
         or not all(isinstance(dim, int) and dim > 0 for dim in new_size)
     ):
-        raise ValueError("'new_size' must be a tuple of two positive integers.")
+        raise ValueError("'new_size' must be a tuple of two positive integers")
 
-    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
-    resized = cv2.resize(np_image, new_size, interpolation=cv2.INTER_LINEAR)
-    
-    if output_image_path:
-        print(IOHandler.save_image(resized, output_image_path))
+    # Resize using bilinear interpolation
+    resized = cv2.resize(image._data, new_size, interpolation=cv2.INTER_LINEAR)
     
-    return resized
+    return Result(
+        image=resized,
+        meta={
+            "source": image,
+            "operation": "resize_image",
+            "new_size": new_size
+        }
+    )