Batch Open-vocabulary Detection with Grounding Models

configs/OWLv2_detection/config_owlv2_detect_image_folder_template.yaml

@@ -0,0 +1,42 @@
+# =============================================================================
+# Configuration File for OWLv2 Zero-Shot Detection from Image Folders
+# =============================================================================
+
+# ---------------------------
+# Detection Parameters
+# ---------------------------
+text_labels:
+  - fish
+  - shark
+  - whale
+confidence_threshold: 0.1   # Minimum confidence score for detections
+
+# ---------------------------
+# DataLoader Configurations
+# ---------------------------
+batch_size: 16
+num_workers: 20
+prefetch_factor: 16
+
+# ---------------------------
+# Image Processing Settings
+# ---------------------------
+validate_images: false      # Validate images with PIL (slower but catches corrupted files)
+uuid_mode: filename         # Options: filename, relative, fullpath, hash
+
+# ---------------------------
+# Distributed Processing
+# ---------------------------
+evenly_distribute: true
+stagger: false
+
+# ---------------------------
+# Output Configurations
+# ---------------------------
+max_uuids_per_file: 10000
+out_prefix: OWLv2_detection_results
+
+# =============================================================================
+# USAGE:
+# python OWLv2_detect.py /path/to/images /path/to/output --input_type images --config config_owlv2_detect_image_folder_template.yaml
+# =============================================================================

configs/OWLv2_detection/config_owlv2_detect_parquet_template.yaml

@@ -0,0 +1,49 @@
+# =============================================================================
+# Configuration File for OWLv2 Zero-Shot Detection from Parquet Files
+# =============================================================================
+
+# ---------------------------
+# Detection Parameters
+# ---------------------------
+text_labels:
+  - fish
+  - shark
+  - whale
+confidence_threshold: 0.1   # Minimum confidence score for detections
+
+# ---------------------------
+# DataLoader Configurations
+# ---------------------------
+batch_size: 16
+num_workers: 20
+prefetch_factor: 16
+
+# ---------------------------
+# Parquet-Specific Settings
+# ---------------------------
+read_batch_size: 128
+read_columns:
+  - uuid
+  - image
+  - original_size
+  - resized_size
+
+# ---------------------------
+# Distributed Processing
+# ---------------------------
+evenly_distribute: true
+stagger: false
+
+# ---------------------------
+# Output Configurations
+# ---------------------------
+max_uuids_per_file: 10000
+out_prefix: OWLv2_detection_results
+
+# =============================================================================
+# USAGE:
+# python OWLv2_detect.py /path/to/parquet_dir /path/to/output --input_type parquet --config config_owlv2_detect_parquet_template.yaml
+#
+# With file list:
+# python OWLv2_detect.py /path/to/parquet_dir /path/to/output --input_type parquet --file_list files.txt --config config_owlv2_detect_parquet_template.yaml
+# =============================================================================

configs/animal_detection/config_animal_detect_image_folder_template.yaml

@@ -0,0 +1,152 @@
+# =============================================================================
+# Configuration File for Batch Animal Detection from Image Folders
+# =============================================================================
+# This configuration is optimized for animal detection on image files directly
+# from a directory structure using MegaDetector models.
+# -----------------------------------------------------------------------------
+
+# ---------------------------
+# Model Configuration
+# ---------------------------
+# MegaDetector model for animal detection
+model:
+  weights: MDV6-yolov10-e-1280.pt      # MegaDetector model weights
+                                       # https://microsoft.github.io/CameraTraps/model_zoo/megadetector/
+
+# ---------------------------
+# Detection Parameters
+# ---------------------------
+confidence_threshold: 0.2   # Minimum confidence score for animal detections
+                            # MegaDetector typically uses 0.2 as default threshold
+                            # Lower values = more detections (including false positives)
+                            # Higher values = fewer, more confident detections
+
+image_size: 1280            # Input image size for the model (square format)
+                            # Common values: 640, 1024, 1280
+                            # Larger sizes may improve detection accuracy but increase processing time
+
+# ---------------------------
+# DataLoader Configurations
+# ---------------------------
+batch_size: 16              # Number of images per batch (adjust based on GPU memory)
+                            # Animal detection (especially MegaDetector) can be memory-intensive
+                            # Start with smaller batch sizes and increase if memory allows
+num_workers: 20             # Number of worker processes for data loading
+prefetch_factor: 8          # Number of batches prefetched by each worker
+
+# ---------------------------
+# Image Processing Settings
+# ---------------------------
+validate_images: false      # Set to true to validate all images can be opened with PIL
+                            # Slower startup but catches corrupted files
+
+# How to generate unique IDs from image file paths
+uuid_mode: filename         # Options:
+                            # - "filename": image001.jpg
+                            # - "relative": subfolder/image001.jpg
+                            # - "fullpath": /full/path/to/image001.jpg
+                            # - "hash": MD5 hash of full path
+
+# ---------------------------
+# Distributed Processing
+# ---------------------------
+evenly_distribute: true     # Distribute files based on size for load balancing
+stagger: false              # Stagger worker start times to reduce file system load
+
+# ---------------------------
+# Output Configurations
+# ---------------------------
+max_rows_per_file: 100000             # Maximum number of detection results per output file
+                                      # Animal detection results can be large due to multiple detections per image
+out_prefix: animal_detection_results  # Prefix for output files
+
+# =============================================================================
+# USAGE EXAMPLE:
+# =============================================================================
+# python animal_detect.py /path/to/images /path/to/output --input_type images --config config_animal_detect_image_folder_template.yaml
+# =============================================================================
+
+# =============================================================================
+# IMAGE DIRECTORY REQUIREMENTS:
+# =============================================================================
+# Your image directory can have any structure:
+#
+# Flat structure:
+# /images/
+#   ├── image001.jpg
+#   ├── image002.png
+#   └── image003.jpeg
+#
+# Nested structure:
+# /images/
+#   ├── category1/
+#   │   ├── img1.jpg
+#   │   └── img2.png
+#   └── category2/
+#       ├── img3.jpg
+#       └── img4.png
+#
+# Supported formats: .jpg, .jpeg, .png, .bmp, .tif, .tiff, .webp
+# All images are automatically converted to RGB mode for processing.
+#
+# UUID GENERATION MODES:
+# - filename: Good for flat directories with unique filenames
+# - relative: Good for nested directories where path info is important
+# - fullpath: Good when you need absolute path traceability
+# - hash: Good for very long paths or when you want anonymized IDs
+# =============================================================================
+
+# =============================================================================
+# OUTPUT FORMAT:
+# =============================================================================
+# The script outputs Parquet files containing:
+# - uuid: Unique identifier for each image (based on uuid_mode)
+# - max_detection_score: Maximum confidence score across all detections (0.0 if no animals detected)
+# - num_detections: Total number of detections above threshold
+# - detections: JSON string containing detailed detection information
+#
+# Each detection includes:
+# - bbox: Absolute pixel coordinates [x1, y1, x2, y2]
+# - bbox_normalized: Normalized coordinates [0-1]
+# - confidence: Detection confidence score
+# - class_id: Numeric class ID (0=animal, 1=person, 2=vehicle for MegaDetector)
+# - class_name: Human-readable class name
+#
+# Files are saved in: {output_dir}/detections/rank_{rank}/
+# Example output:
+# animal_detection_results_rank_0_0.parquet
+# animal_detection_results_rank_0_1.parquet
+# ...
+# =============================================================================
+
+# =============================================================================
+# PERFORMANCE TUNING GUIDELINES:
+# =============================================================================
+# 
+# GPU Memory Optimization:
+# - Reduce batch_size if running out of GPU memory
+# - MegaDetector can be memory-intensive, especially at high resolutions
+# - Consider using smaller image_size if memory is limited
+#
+# CPU/I-O Optimization:
+# - Increase num_workers for faster data loading & prevent OOM crashes
+# - Increase prefetch_factor for better pipeline utilization
+#
+# Distributed Processing:
+# - Use evenly_distribute=true for better load balancing
+# - Set stagger=true if experiencing file system bottlenecks
+#
+# Detection Quality vs Speed:
+# - MegaDetector confidence_threshold of 0.2 is typically optimal based on repo documentation
+# - Lower thresholds may find more animals but increase false positives
+# - Higher image_size improves accuracy but slows processing
+# - Choose appropriate model based on accuracy vs speed needs:
+#   * MegaDetectorV6-Ultralytics-YoloV10-Extra: Most accurate, best for wildlife
+#   * YOLOv8 variants: General purpose object detection
+#
+# Model-Specific Notes:
+# - MegaDetector is specifically trained for wildlife camera trap images
+# - It detects animals and people with high accuracy
+# - Works well on images from outdoor/natural settings
+# - May not perform as well on indoor or urban animal images
+# =============================================================================