Detection

configs/animal_detection/config_animal_detect_hdf5_template.yaml

@@ -0,0 +1,200 @@
+# =============================================================================
+# Configuration File for Batch Animal Detection from HDF5 Files
+# =============================================================================
+# This configuration is optimized for animal detection on HDF5 files containing
+# image data with metadata using MegaDetector models.
+# -----------------------------------------------------------------------------
+
+# ---------------------------
+# Model Configuration
+# ---------------------------
+# MegaDetector model for animal detection
+model:
+  weights: md_v5a.0.0.pt      # MegaDetector model weights
+                              # Options:
+                              # - md_v5a.0.0.pt (MegaDetector v5a, recommended)
+                              # - md_v5b.0.0.pt (MegaDetector v5b, alternative)
+                              # - yolov8n.pt (YOLOv8 nano, general purpose)
+                              # - yolov8s.pt (YOLOv8 small, balanced)
+                              # - yolov8m.pt (YOLOv8 medium, more accurate)
+                              # - yolov8l.pt (YOLOv8 large, most accurate)
+                              # Custom trained models are also supported
+                              # For MegaDetector models, see:
+                              # https://github.com/microsoft/CameraTraps
+
+# ---------------------------
+# 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)
+                            # MegaDetector v5 typically uses 1280
+                            # Common values: 640, 1024, 1280
+                            # Larger sizes may improve detection accuracy but increase processing time
+
+# ---------------------------
+# DataLoader Configurations
+# ---------------------------
+batch_size: 8               # 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: 24             # Number of worker processes for data loading
+prefetch_factor: 8          # Number of batches prefetched by each worker
+
+# ---------------------------
+# HDF5-Specific Settings
+# ---------------------------
+# HDF5 dataset structure requirements:
+# - Files contain a group named 'images' (default, configurable)
+# - Within the 'images' group, each image is stored as a separate dataset
+# - Dataset name = UUID (e.g., 'image_uuid_det123')
+# - Each dataset contains encoded image bytes (JPEG/PNG/WebP format)
+# - Structure: file['images']['uuid'] = encoded_image_bytes
+#
+# Example structure:
+# my_images.h5
+# └── images/              (group)
+#     ├── img_001          (dataset: encoded JPEG bytes)
+#     ├── img_002          (dataset: encoded PNG bytes)
+#     └── img_003          (dataset: encoded WebP bytes)
+# More details in the HDF5 DATA REQUIREMENTS section below.
+
+# ---------------------------
+# Distributed Processing
+# ---------------------------
+evenly_distribute: true     # Distribute files based on size for load balancing
+stagger: false              # Stagger worker start times to reduce I/O congestion
+
+# ---------------------------
+# Output Configurations
+# ---------------------------
+max_rows_per_file: 5000             # 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 EXAMPLES:
+# =============================================================================
+# 
+# For HDF5 files:
+# python animal_detect.py /path/to/hdf5_dir /path/to/output --input_type hdf5 --config config_animal_detect_hdf5_template.yaml
+#
+# With file list:
+# python animal_detect.py /path/to/hdf5_dir /path/to/output --input_type hdf5 --file_list files.txt --config config_animal_detect_hdf5_template.yaml
+# =============================================================================
+
+# =============================================================================
+# HDF5 DATA REQUIREMENTS:
+# =============================================================================
+# Your HDF5 files must follow this structure:
+# 1. A group named 'images' (default, or specify custom group_name)
+# 2. Within the group, each image is a separate dataset named by its UUID
+# 3. Each dataset contains encoded image bytes (JPEG/PNG/WebP format)
+#
+# Required structure:
+# file.h5
+# └── images/                    (group)
+#     ├── uuid1                  (dataset: encoded image bytes)
+#     ├── uuid2                  (dataset: encoded image bytes)
+#     └── uuid3                  (dataset: encoded image bytes)
+#
+# How to create compatible HDF5 files:
+# ```python
+# import h5py
+# from PIL import Image
+# import io
+# import numpy as np
+#
+# with h5py.File('output.h5', 'w') as f:
+#     images_group = f.create_group('images')
+#     
+#     # For each image:
+#     img = Image.open('photo.jpg')
+#     img_bytes = io.BytesIO()
+#     img.save(img_bytes, format='JPEG')
+#     
+#     # Store with UUID as dataset name
+#     images_group.create_dataset(
+#         'img_001',
+#         data=np.frombuffer(img_bytes.getvalue(), dtype=np.uint8)
+#     )
+# ```
+# =============================================================================
+
+# =============================================================================
+# OUTPUT FORMAT:
+# =============================================================================
+# The script outputs Parquet files containing:
+# - uuid: Unique identifier for each image (from input HDF5)
+# - 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 in the JSON 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
+# ...
+#
+# Example detection JSON structure:
+# [
+#   {
+#     "bbox": [120.5, 80.2, 340.8, 290.1],
+#     "bbox_normalized": [0.118, 0.078, 0.333, 0.284],
+#     "confidence": 0.85,
+#     "class_id": 0,
+#     "class_name": "animal"
+#   },
+#   {
+#     "bbox": [450.0, 200.0, 600.0, 400.0],
+#     "bbox_normalized": [0.440, 0.195, 0.586, 0.391],
+#     "confidence": 0.72,
+#     "class_id": 1,
+#     "class_name": "person"
+#   }
+# ]
+# =============================================================================
+
+# =============================================================================
+# 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 (but watch CPU usage)
+# - Increase prefetch_factor for better pipeline utilization
+# - HDF5 files provide efficient random access for large datasets
+#
+# Distributed Processing:
+# - Use evenly_distribute=true for better load balancing
+# - Set stagger=true if experiencing I/O bottlenecks
+#
+# Detection Quality vs Speed:
+# - MegaDetector confidence_threshold of 0.2 is typically optimal
+# - 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:
+#   * md_v5a.0.0.pt: Best for wildlife/camera trap images
+#   * YOLOv8 variants: General purpose object detection
+#
+# Model-Specific Notes:
+# - MegaDetector is specifically trained for wildlife camera trap images
+# - It detects animals, people, and vehicles with high accuracy
+# - Works well on images from outdoor/natural settings
+# - May not perform as well on indoor or urban animal images
+# - Provides both detection and rough classification capabilities
+# =============================================================================

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
+# =============================================================================