distant-frames 0.2.2__tar.gz → 0.3.0__tar.gz

{distant_frames-0.2.2 → distant_frames-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: distant-frames
-Version: 0.2.2
+Version: 0.3.0
 Summary: Smart video frame extraction tool
 Project-URL: Homepage, https://github.com/yubraaj11/distant-frames
 Project-URL: Repository, https://github.com/yubraaj11/distant-frames
@@ -38,6 +38,8 @@ Description-Content-Type: text/markdown
 - **Histogram Correlation**: Uses HSV color space histogram comparison for robust similarity detection.
 - **Configurable Threshold**: Fine-tune the sensitivity of frame dropping to suit your specific video content.
 - **Efficient Processing**: Seeks directly to target timestamps (`CAP_PROP_POS_FRAMES`) for faster processing than frame-by-frame reading.
+- **Custom Start Time**: Begin extraction from any point in the video using a timestamp in seconds.
+- **Open Eyes Filter**: Optionally keep only frames where at least one face with both eyes open is detected, using local Haar cascade classifiers.
 
 ## 🛠️ Prerequisites
 
@@ -89,7 +91,9 @@ distant-frames path/to/video.mp4 -o path/to/output -t 0.75
 |----------|-------------|---------|
 | `video_path` | Path to the input video file (Required). | N/A |
 | `--output`, `-o` | Directory to save the extracted frames. | `extracted_frames` |
-| `--threshold`, `-t` | Defines the similarity score threshold (0.0 to 1.0) between frames. If the similarity score is **higher** than this value, the frame will be discarded. | `0.65` |
+| `--threshold`, `-t` | Similarity score threshold (0.0 to 1.0). Frames with a score **higher** than this value are discarded. | `0.65` |
+| `--start`, `-s` | Timestamp in seconds to begin extraction from. | `0.0` |
+| `--open-eyes` | When set, only saves frames where at least one face with both eyes open is detected. | Off |
 
 ### Examples
 
@@ -103,14 +107,30 @@ distant-frames my_vacation.mp4
 distant-frames my_vacation.mp4 -o best_shots -t 0.95
 ```
 
+**Start extraction from a specific timestamp (e.g. 1 minute 30 seconds in):**
+```bash
+distant-frames interview.mp4 -s 90
+```
+
+**Only keep frames where a person's eyes are open:**
+```bash
+distant-frames interview.mp4 --open-eyes -o key_frames
+```
+
+**Combine all options:**
+```bash
+distant-frames interview.mp4 -s 90 -t 0.80 --open-eyes -o key_frames
+```
+
 ## 🔍 How It Works
 
-1. **Sampling**: The script checks one frame every second (based on the video's FPS).
+1. **Sampling**: The script checks one frame every second (based on the video's FPS), starting from `--start` if provided.
 2. **Comparison**: It compares the current candidate frame against the **last successfully saved frame**.
 3. **Algorithm**: It converts frames to HSV color space and calculates Normalized Histogram Correlation.
 4. **Decision**:
-   - If similarity < `threshold`: **SAVE** (The scene has changed).
+   - If similarity < `threshold`: candidate for saving.
    - If similarity >= `threshold`: **SKIP** (The scene is too similar).
+5. **Open Eyes Filter** *(optional)*: If `--open-eyes` is set, a candidate frame is only saved if a face with two open eyes is detected using Haar cascade classifiers.
 
 ## 🧪 Testing
 

{distant_frames-0.2.2 → distant_frames-0.3.0}/README.md

@@ -14,6 +14,8 @@
 - **Histogram Correlation**: Uses HSV color space histogram comparison for robust similarity detection.
 - **Configurable Threshold**: Fine-tune the sensitivity of frame dropping to suit your specific video content.
 - **Efficient Processing**: Seeks directly to target timestamps (`CAP_PROP_POS_FRAMES`) for faster processing than frame-by-frame reading.
+- **Custom Start Time**: Begin extraction from any point in the video using a timestamp in seconds.
+- **Open Eyes Filter**: Optionally keep only frames where at least one face with both eyes open is detected, using local Haar cascade classifiers.
 
 ## 🛠️ Prerequisites
 
@@ -65,7 +67,9 @@ distant-frames path/to/video.mp4 -o path/to/output -t 0.75
 |----------|-------------|---------|
 | `video_path` | Path to the input video file (Required). | N/A |
 | `--output`, `-o` | Directory to save the extracted frames. | `extracted_frames` |
-| `--threshold`, `-t` | Defines the similarity score threshold (0.0 to 1.0) between frames. If the similarity score is **higher** than this value, the frame will be discarded. | `0.65` |
+| `--threshold`, `-t` | Similarity score threshold (0.0 to 1.0). Frames with a score **higher** than this value are discarded. | `0.65` |
+| `--start`, `-s` | Timestamp in seconds to begin extraction from. | `0.0` |
+| `--open-eyes` | When set, only saves frames where at least one face with both eyes open is detected. | Off |
 
 ### Examples
 
@@ -79,14 +83,30 @@ distant-frames my_vacation.mp4
 distant-frames my_vacation.mp4 -o best_shots -t 0.95
 ```
 
+**Start extraction from a specific timestamp (e.g. 1 minute 30 seconds in):**
+```bash
+distant-frames interview.mp4 -s 90
+```
+
+**Only keep frames where a person's eyes are open:**
+```bash
+distant-frames interview.mp4 --open-eyes -o key_frames
+```
+
+**Combine all options:**
+```bash
+distant-frames interview.mp4 -s 90 -t 0.80 --open-eyes -o key_frames
+```
+
 ## 🔍 How It Works
 
-1. **Sampling**: The script checks one frame every second (based on the video's FPS).
+1. **Sampling**: The script checks one frame every second (based on the video's FPS), starting from `--start` if provided.
 2. **Comparison**: It compares the current candidate frame against the **last successfully saved frame**.
 3. **Algorithm**: It converts frames to HSV color space and calculates Normalized Histogram Correlation.
 4. **Decision**:
-   - If similarity < `threshold`: **SAVE** (The scene has changed).
+   - If similarity < `threshold`: candidate for saving.
    - If similarity >= `threshold`: **SKIP** (The scene is too similar).
+5. **Open Eyes Filter** *(optional)*: If `--open-eyes` is set, a candidate frame is only saved if a face with two open eyes is detected using Haar cascade classifiers.
 
 ## 🧪 Testing
 

{distant_frames-0.2.2 → distant_frames-0.3.0}/distant_frames/cli.py

@@ -35,15 +35,30 @@ def main(
             max=1.0,
             help="Similarity threshold (0.0-1.0). Higher values mean stricter deduplication (fewer frames saved)."
         )
-    ] = 0.65,
+    ] = 0.75,
+    start_time: Annotated[
+        float,
+        typer.Option(
+            "--start", "-s",
+            min=0.0,
+            help="Start extraction from this timestamp (in seconds). Defaults to 0 (beginning of video)."
+        )
+    ] = 0.0,
+    open_eyes_only: Annotated[
+        bool,
+        typer.Option(
+            "--open-eyes",
+            help="Only save frames where at least one face with both eyes open is detected."
+        )
+    ] = False,
 ):
     """
     Extract distinct frames from a video file based on visual similarity.
-    
+
     The tool samples the video at 1-second intervals and compares consecutive frames.
     Frames that are too similar to previously saved frames are automatically skipped.
     """
-    extract_frames(str(video_path), output, threshold)
+    extract_frames(str(video_path), output, threshold, start_time, open_eyes_only)
 
 if __name__ == "__main__":
     app()

{distant_frames-0.2.2 → distant_frames-0.3.0}/distant_frames/core.py

@@ -3,6 +3,32 @@ import os
 from pathlib import Path
 import uuid
 
+_CASCADES_DIR = Path(__file__).parent.parent / "haarcascade_classifiers"
+
+def _load_eye_cascades():
+    """Load and return (face_cascade, eye_cascade) from the local haarcascade_classifiers/ directory."""
+    face_path = str(_CASCADES_DIR / "haarcascade_frontalface_default.xml")
+    eye_path = str(_CASCADES_DIR / "haarcascade_eye.xml")
+    face_cascade = cv2.CascadeClassifier(face_path)
+    eye_cascade = cv2.CascadeClassifier(eye_path)
+    if face_cascade.empty() or eye_cascade.empty():
+        raise RuntimeError(
+            f"Failed to load Haar cascade classifiers from {_CASCADES_DIR}. "
+            "Ensure haarcascade_frontalface_default.xml and haarcascade_eye.xml exist there."
+        )
+    return face_cascade, eye_cascade
+
+def has_open_eyes(frame, face_cascade, eye_cascade):
+    """Return True if at least one face with two detected (open) eyes is found in the frame."""
+    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+    faces = face_cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(30, 30))
+    for (x, y, w, h) in faces:
+        roi = gray[y:y + h, x:x + w]
+        eyes = eye_cascade.detectMultiScale(roi, scaleFactor=1.1, minNeighbors=5)
+        if len(eyes) >= 2:
+            return True
+    return False
+
 def calculate_similarity(frame1, frame2):
     """Calculates similarity between two frames using Histogram Correlation.
 
@@ -34,13 +60,14 @@ def calculate_similarity(frame1, frame2):
     similarity = cv2.compareHist(hist1, hist2, cv2.HISTCMP_CORREL)
     return similarity
 
-def extract_frames(video_path, output_folder, threshold=0.65):
+def extract_frames(video_path, output_folder, threshold=0.65, start_time=0.0, open_eyes_only=False):
     """Extracts distinct frames from a video file based on visual similarity.
 
-    The function samples the video at 1-second intervals. It compares the current
-    frame with the last saved frame. If the similarity score is below the
-    specified threshold, the frame is considered distinct and saved.
-    
+    The function samples the video at 1-second intervals starting from
+    `start_time`. It compares the current frame with the last saved frame.
+    If the similarity score is below the specified threshold, the frame is
+    considered distinct and saved.
+
     If a frame is skipped (similar to the last saved frame), the next comparison
     will be performed against the *previous* saved frame (if available) to ensure
     robustness against gradual changes or local similarities.
@@ -51,8 +78,12 @@ def extract_frames(video_path, output_folder, threshold=0.65):
             The directory will be created if it does not exist.
         threshold (float, optional): Similarity threshold (0.0 to 1.0).
             Frames with similarity higher than this value regarding the last
-            saved frame will be dropped. Higher values mean stricter
-            deduplication (fewer frames saved). Defaults to 0.65.
+            saved frame will be dropped. Defaults to 0.65.
+        start_time (float, optional): Timestamp in seconds from which to begin
+            extraction. Defaults to 0.0 (beginning of video).
+        open_eyes_only (bool, optional): When True, only frames where at least
+            one face with two open eyes is detected are saved. Uses OpenCV
+            Haar cascade classifiers. Defaults to False.
 
     Returns:
         None
@@ -64,6 +95,8 @@ def extract_frames(video_path, output_folder, threshold=0.65):
     if not os.path.exists(output_folder):
         os.makedirs(output_folder)
 
+    face_cascade, eye_cascade = (_load_eye_cascades() if open_eyes_only else (None, None))
+
     video_file_name = Path(video_path).stem
     cap = cv2.VideoCapture(str(video_path))
     if not cap.isOpened():
@@ -75,12 +108,19 @@ def extract_frames(video_path, output_folder, threshold=0.65):
         print("Error: Could not retrieve FPS.")
         return
 
-    print(f"Video FPS: {fps}")
-    
+    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    duration = total_frames / fps
+    if start_time >= duration:
+        print(f"Error: start_time ({start_time:.1f}s) is beyond the video duration ({duration:.1f}s).")
+        cap.release()
+        return
+
+    print(f"Video FPS: {fps} | Duration: {duration:.1f}s | Starting at: {start_time:.1f}s")
+
     # We want to check frames every 1 second
     frame_interval = int(fps)
-    
-    current_frame_idx = 0
+
+    current_frame_idx = int(start_time * fps)
     saved_count = 0
     last_saved_frame = None
     last_saved_timestamp = None
@@ -131,6 +171,11 @@ def extract_frames(video_path, output_folder, threshold=0.65):
                 skip_reference_frame = last_saved_frame
                 skip_reference_timestamp = last_saved_timestamp
 
+        if should_save and open_eyes_only:
+            if not has_open_eyes(frame, face_cascade, eye_cascade):
+                print(f"[{timestamp:.1f}s] Open-eyes check failed → SKIP")
+                should_save = False
+
         if should_save:
             output_filename = os.path.join(output_folder, f"{video_file_name}_frame_{uuid.uuid4().hex[:8]}.jpg")
             cv2.imwrite(output_filename, frame)