vogel-video-analyzer 0.1.0__tar.gz

vogel_video_analyzer-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-11-06
+
+### Added
+- Initial release of vogel-video-analyzer
+- YOLOv8-based bird detection in videos
+- Command-line interface (`vogel-analyze`)
+- Python library API (`VideoAnalyzer` class)
+- Configurable sample rate for performance optimization
+- Segment detection for continuous bird presence
+- JSON export functionality
+- Auto-delete feature for videos without bird content
+- Structured logging support
+- Model search in multiple directories
+- Comprehensive documentation and examples
+
+### Features
+- Frame-by-frame video analysis
+- Bird content percentage calculation
+- Detailed statistics generation
+- Multiple video batch processing
+- Progress indicators
+- Formatted console reports
+
+### Technical
+- Python 3.8+ support
+- OpenCV integration
+- Ultralytics YOLOv8 integration
+- MIT License
+- PyPI package structure with modern pyproject.toml
+
+---
+
+[0.1.0]: https://github.com/kamera-linux/vogel-video-analyzer/releases/tag/v0.1.0

vogel_video_analyzer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vogel-Kamera-Linux Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vogel_video_analyzer-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include src *.py

vogel_video_analyzer-0.1.0/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: vogel-video-analyzer
+Version: 0.1.0
+Summary: YOLOv8-based video analysis tool for bird content detection
+Author-email: Vogel-Kamera-Linux Team <info@vogel-kamera-linux.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kamera-linux/vogel-video-analyzer
+Project-URL: Documentation, https://github.com/kamera-linux/vogel-video-analyzer#readme
+Project-URL: Repository, https://github.com/kamera-linux/vogel-video-analyzer
+Project-URL: Issues, https://github.com/kamera-linux/vogel-video-analyzer/issues
+Project-URL: Parent Project, https://github.com/kamera-linux/vogel-kamera-linux
+Keywords: video,analysis,bird,detection,yolov8,opencv,computer-vision,wildlife,ornithology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: ultralytics>=8.0.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# 🐦 Vogel Video Analyzer
+
+[![PyPI version](https://badge.fury.io/py/vogel-video-analyzer.svg)](https://badge.fury.io/py/vogel-video-analyzer)
+[![Python Versions](https://img.shields.io/pypi/pyversions/vogel-video-analyzer.svg)](https://pypi.org/project/vogel-video-analyzer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://pepy.tech/badge/vogel-video-analyzer)](https://pepy.tech/project/vogel-video-analyzer)
+
+**YOLOv8-based video analysis tool for automated bird content detection and quantification.**
+
+A powerful command-line tool and Python library for analyzing videos to detect and quantify bird presence using state-of-the-art YOLOv8 object detection.
+
+---
+
+## ✨ Features
+
+- 🤖 **YOLOv8-powered Detection** - Accurate bird detection using pre-trained models
+- 📊 **Detailed Statistics** - Frame-by-frame analysis with bird content percentage
+- 🎯 **Segment Detection** - Identifies continuous time periods with bird presence
+- ⚡ **Performance Optimized** - Configurable sample rate for faster processing
+- 📄 **JSON Export** - Structured reports for archival and further analysis
+- 🗑️ **Auto-Delete** - Automatically removes videos without bird content
+- 📝 **Logging Support** - Structured logs for batch processing workflows
+- 🐍 **Library & CLI** - Use as standalone tool or integrate into your Python projects
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install vogel-video-analyzer
+```
+
+### Basic Usage
+
+```bash
+# Analyze a single video
+vogel-analyze video.mp4
+
+# Faster analysis (every 5th frame)
+vogel-analyze --sample-rate 5 video.mp4
+
+# Export to JSON
+vogel-analyze --output report.json video.mp4
+
+# Batch process directory
+vogel-analyze ~/Videos/Birds/**/*.mp4
+```
+
+---
+
+## 📖 Usage Examples
+
+### Command Line Interface
+
+#### Basic Analysis
+```bash
+# Analyze single video with default settings
+vogel-analyze bird_video.mp4
+```
+
+**Output:**
+```
+🎬 Video Analysis Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📁 File: /path/to/bird_video.mp4
+📊 Total Frames: 450 (analyzed: 90)
+⏱️  Duration: 15.0 seconds
+🐦 Bird Frames: 72 (80.0%)
+🎯 Bird Segments: 2
+
+📍 Detected Segments:
+  ┌ Segment 1: 00:00:02 - 00:00:08 (72% bird frames)
+  └ Segment 2: 00:00:11 - 00:00:14 (89% bird frames)
+
+✅ Status: Significant bird activity detected
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+#### Advanced Options
+```bash
+# Custom threshold and sample rate
+vogel-analyze --threshold 0.4 --sample-rate 10 video.mp4
+
+# Batch processing with auto-delete
+vogel-analyze --sample-rate 5 --delete ~/Videos/Birds/**/*.mp4
+
+# Save JSON report and log
+vogel-analyze --output report.json --log video.mp4
+```
+
+### Python Library
+
+```python
+from vogel_video_analyzer import VideoAnalyzer
+
+# Initialize analyzer
+analyzer = VideoAnalyzer(
+    model_path="yolov8n.pt",
+    threshold=0.3
+)
+
+# Analyze video
+stats = analyzer.analyze_video("bird_video.mp4", sample_rate=5)
+
+# Print formatted report
+analyzer.print_report(stats)
+
+# Access statistics
+print(f"Bird content: {stats['bird_percentage']:.1f}%")
+print(f"Segments found: {len(stats['bird_segments'])}")
+```
+
+---
+
+## 🎯 Use Cases
+
+### 1. Quality Control for Bird Recordings
+Automatically verify that recorded videos actually contain birds:
+
+```bash
+vogel-analyze --threshold 0.5 --delete recordings/**/*.mp4
+```
+
+### 2. Archive Management
+Identify and remove videos without bird content to save storage:
+
+```bash
+# Find videos with 0% bird content
+vogel-analyze --output stats.json archive/**/*.mp4
+
+# Delete empty videos
+vogel-analyze --delete archive/**/*.mp4
+```
+
+### 3. Batch Analysis for Research
+Process large video collections and generate structured reports:
+
+```bash
+# Analyze all videos and save individual reports
+for video in research_data/**/*.mp4; do
+    vogel-analyze --sample-rate 10 --output "${video%.mp4}_report.json" "$video"
+done
+```
+
+### 4. Integration in Automation Workflows
+Use as part of automated recording pipelines:
+
+```python
+from vogel_video_analyzer import VideoAnalyzer
+
+analyzer = VideoAnalyzer(threshold=0.3)
+stats = analyzer.analyze_video("latest_recording.mp4", sample_rate=5)
+
+# Only keep videos with significant bird content
+if stats['bird_percentage'] < 10:
+    print("Insufficient bird content, deleting...")
+    # Handle deletion
+else:
+    print(f"✅ Quality video: {stats['bird_percentage']:.1f}% bird content")
+```
+
+---
+
+## ⚙️ Configuration Options
+
+| Option | Description | Default | Values |
+|--------|-------------|---------|--------|
+| `--model` | YOLO model to use | `yolov8n.pt` | Any YOLO model |
+| `--threshold` | Confidence threshold | `0.3` | `0.0` - `1.0` |
+| `--sample-rate` | Analyze every Nth frame | `5` | `1` - `∞` |
+| `--output` | Save JSON report | - | File path |
+| `--delete` | Auto-delete 0% videos | `False` | Flag |
+| `--log` | Enable logging | `False` | Flag |
+
+### Sample Rate Recommendations
+
+| Video FPS | Sample Rate | Frames Analyzed | Performance |
+|-----------|-------------|----------------|-------------|
+| 30 fps | 1 | 100% (all frames) | Slow, highest precision |
+| 30 fps | 5 | 20% | ⭐ **Recommended** - Good balance |
+| 30 fps | 10 | 10% | Fast, sufficient |
+| 30 fps | 20 | 5% | Very fast, basic check |
+
+### Threshold Values
+
+| Threshold | Description | Use Case |
+|-----------|-------------|----------|
+| 0.2 | Very sensitive | Detects distant/partially obscured birds |
+| 0.3 | **Standard** | Balanced detection |
+| 0.5 | Conservative | Only clearly visible birds |
+| 0.7 | Very strict | Only perfect detections |
+
+---
+
+## 🔍 Technical Details
+
+### Model Search Hierarchy
+
+The analyzer searches for YOLOv8 models in this order:
+
+1. `models/` directory (local)
+2. `config/models/` directory
+3. Current directory
+4. Auto-download from Ultralytics (fallback)
+
+### Detection Algorithm
+
+- **Target Class:** Bird (COCO class 14)
+- **Inference:** Frame-by-frame YOLOv8 detection
+- **Segment Detection:** Groups consecutive bird frames with max 2-second gaps
+- **Performance:** ~5x speedup with sample-rate=5 on 30fps videos
+
+### Output Format
+
+JSON reports include:
+```json
+{
+  "video_file": "bird_video.mp4",
+  "duration_seconds": 15.0,
+  "total_frames": 450,
+  "frames_analyzed": 90,
+  "bird_percentage": 80.0,
+  "bird_segments": [
+    {
+      "start": 2.0,
+      "end": 8.0,
+      "detections": 36
+    }
+  ]
+}
+```
+
+---
+
+## 📚 Documentation
+
+- **GitHub Repository:** [vogel-video-analyzer](https://github.com/kamera-linux/vogel-video-analyzer)
+- **Parent Project:** [vogel-kamera-linux](https://github.com/kamera-linux/vogel-kamera-linux)
+- **Issue Tracker:** [GitHub Issues](https://github.com/kamera-linux/vogel-video-analyzer/issues)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! We appreciate bug reports, feature suggestions, documentation improvements, and code contributions.
+
+Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
+- How to set up your development environment
+- Our code style and guidelines
+- The pull request process
+- How to report bugs and suggest features
+
+For security vulnerabilities, please see our [Security Policy](SECURITY.md).
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- **Ultralytics YOLOv8** - Powerful object detection framework
+- **OpenCV** - Computer vision library
+- **Vogel-Kamera-Linux** - Parent project for automated bird observation
+
+---
+
+## 📞 Support
+
+- **Issues:** [GitHub Issues](https://github.com/kamera-linux/vogel-video-analyzer/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/kamera-linux/vogel-video-analyzer/discussions)
+
+---
+
+**Made with ❤️ by the Vogel-Kamera-Linux Team**

vogel_video_analyzer-0.1.0/README.md

@@ -0,0 +1,280 @@
+# 🐦 Vogel Video Analyzer
+
+[![PyPI version](https://badge.fury.io/py/vogel-video-analyzer.svg)](https://badge.fury.io/py/vogel-video-analyzer)
+[![Python Versions](https://img.shields.io/pypi/pyversions/vogel-video-analyzer.svg)](https://pypi.org/project/vogel-video-analyzer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://pepy.tech/badge/vogel-video-analyzer)](https://pepy.tech/project/vogel-video-analyzer)
+
+**YOLOv8-based video analysis tool for automated bird content detection and quantification.**
+
+A powerful command-line tool and Python library for analyzing videos to detect and quantify bird presence using state-of-the-art YOLOv8 object detection.
+
+---
+
+## ✨ Features
+
+- 🤖 **YOLOv8-powered Detection** - Accurate bird detection using pre-trained models
+- 📊 **Detailed Statistics** - Frame-by-frame analysis with bird content percentage
+- 🎯 **Segment Detection** - Identifies continuous time periods with bird presence
+- ⚡ **Performance Optimized** - Configurable sample rate for faster processing
+- 📄 **JSON Export** - Structured reports for archival and further analysis
+- 🗑️ **Auto-Delete** - Automatically removes videos without bird content
+- 📝 **Logging Support** - Structured logs for batch processing workflows
+- 🐍 **Library & CLI** - Use as standalone tool or integrate into your Python projects
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install vogel-video-analyzer
+```
+
+### Basic Usage
+
+```bash
+# Analyze a single video
+vogel-analyze video.mp4
+
+# Faster analysis (every 5th frame)
+vogel-analyze --sample-rate 5 video.mp4
+
+# Export to JSON
+vogel-analyze --output report.json video.mp4
+
+# Batch process directory
+vogel-analyze ~/Videos/Birds/**/*.mp4
+```
+
+---
+
+## 📖 Usage Examples
+
+### Command Line Interface
+
+#### Basic Analysis
+```bash
+# Analyze single video with default settings
+vogel-analyze bird_video.mp4
+```
+
+**Output:**
+```
+🎬 Video Analysis Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📁 File: /path/to/bird_video.mp4
+📊 Total Frames: 450 (analyzed: 90)
+⏱️  Duration: 15.0 seconds
+🐦 Bird Frames: 72 (80.0%)
+🎯 Bird Segments: 2
+
+📍 Detected Segments:
+  ┌ Segment 1: 00:00:02 - 00:00:08 (72% bird frames)
+  └ Segment 2: 00:00:11 - 00:00:14 (89% bird frames)
+
+✅ Status: Significant bird activity detected
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+#### Advanced Options
+```bash
+# Custom threshold and sample rate
+vogel-analyze --threshold 0.4 --sample-rate 10 video.mp4
+
+# Batch processing with auto-delete
+vogel-analyze --sample-rate 5 --delete ~/Videos/Birds/**/*.mp4
+
+# Save JSON report and log
+vogel-analyze --output report.json --log video.mp4
+```
+
+### Python Library
+
+```python
+from vogel_video_analyzer import VideoAnalyzer
+
+# Initialize analyzer
+analyzer = VideoAnalyzer(
+    model_path="yolov8n.pt",
+    threshold=0.3
+)
+
+# Analyze video
+stats = analyzer.analyze_video("bird_video.mp4", sample_rate=5)
+
+# Print formatted report
+analyzer.print_report(stats)
+
+# Access statistics
+print(f"Bird content: {stats['bird_percentage']:.1f}%")
+print(f"Segments found: {len(stats['bird_segments'])}")
+```
+
+---
+
+## 🎯 Use Cases
+
+### 1. Quality Control for Bird Recordings
+Automatically verify that recorded videos actually contain birds:
+
+```bash
+vogel-analyze --threshold 0.5 --delete recordings/**/*.mp4
+```
+
+### 2. Archive Management
+Identify and remove videos without bird content to save storage:
+
+```bash
+# Find videos with 0% bird content
+vogel-analyze --output stats.json archive/**/*.mp4
+
+# Delete empty videos
+vogel-analyze --delete archive/**/*.mp4
+```
+
+### 3. Batch Analysis for Research
+Process large video collections and generate structured reports:
+
+```bash
+# Analyze all videos and save individual reports
+for video in research_data/**/*.mp4; do
+    vogel-analyze --sample-rate 10 --output "${video%.mp4}_report.json" "$video"
+done
+```
+
+### 4. Integration in Automation Workflows
+Use as part of automated recording pipelines:
+
+```python
+from vogel_video_analyzer import VideoAnalyzer
+
+analyzer = VideoAnalyzer(threshold=0.3)
+stats = analyzer.analyze_video("latest_recording.mp4", sample_rate=5)
+
+# Only keep videos with significant bird content
+if stats['bird_percentage'] < 10:
+    print("Insufficient bird content, deleting...")
+    # Handle deletion
+else:
+    print(f"✅ Quality video: {stats['bird_percentage']:.1f}% bird content")
+```
+
+---
+
+## ⚙️ Configuration Options
+
+| Option | Description | Default | Values |
+|--------|-------------|---------|--------|
+| `--model` | YOLO model to use | `yolov8n.pt` | Any YOLO model |
+| `--threshold` | Confidence threshold | `0.3` | `0.0` - `1.0` |
+| `--sample-rate` | Analyze every Nth frame | `5` | `1` - `∞` |
+| `--output` | Save JSON report | - | File path |
+| `--delete` | Auto-delete 0% videos | `False` | Flag |
+| `--log` | Enable logging | `False` | Flag |
+
+### Sample Rate Recommendations
+
+| Video FPS | Sample Rate | Frames Analyzed | Performance |
+|-----------|-------------|----------------|-------------|
+| 30 fps | 1 | 100% (all frames) | Slow, highest precision |
+| 30 fps | 5 | 20% | ⭐ **Recommended** - Good balance |
+| 30 fps | 10 | 10% | Fast, sufficient |
+| 30 fps | 20 | 5% | Very fast, basic check |
+
+### Threshold Values
+
+| Threshold | Description | Use Case |
+|-----------|-------------|----------|
+| 0.2 | Very sensitive | Detects distant/partially obscured birds |
+| 0.3 | **Standard** | Balanced detection |
+| 0.5 | Conservative | Only clearly visible birds |
+| 0.7 | Very strict | Only perfect detections |
+
+---
+
+## 🔍 Technical Details
+
+### Model Search Hierarchy
+
+The analyzer searches for YOLOv8 models in this order:
+
+1. `models/` directory (local)
+2. `config/models/` directory
+3. Current directory
+4. Auto-download from Ultralytics (fallback)
+
+### Detection Algorithm
+
+- **Target Class:** Bird (COCO class 14)
+- **Inference:** Frame-by-frame YOLOv8 detection
+- **Segment Detection:** Groups consecutive bird frames with max 2-second gaps
+- **Performance:** ~5x speedup with sample-rate=5 on 30fps videos
+
+### Output Format
+
+JSON reports include:
+```json
+{
+  "video_file": "bird_video.mp4",
+  "duration_seconds": 15.0,
+  "total_frames": 450,
+  "frames_analyzed": 90,
+  "bird_percentage": 80.0,
+  "bird_segments": [
+    {
+      "start": 2.0,
+      "end": 8.0,
+      "detections": 36
+    }
+  ]
+}
+```
+
+---
+
+## 📚 Documentation
+
+- **GitHub Repository:** [vogel-video-analyzer](https://github.com/kamera-linux/vogel-video-analyzer)
+- **Parent Project:** [vogel-kamera-linux](https://github.com/kamera-linux/vogel-kamera-linux)
+- **Issue Tracker:** [GitHub Issues](https://github.com/kamera-linux/vogel-video-analyzer/issues)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! We appreciate bug reports, feature suggestions, documentation improvements, and code contributions.
+
+Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
+- How to set up your development environment
+- Our code style and guidelines
+- The pull request process
+- How to report bugs and suggest features
+
+For security vulnerabilities, please see our [Security Policy](SECURITY.md).
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- **Ultralytics YOLOv8** - Powerful object detection framework
+- **OpenCV** - Computer vision library
+- **Vogel-Kamera-Linux** - Parent project for automated bird observation
+
+---
+
+## 📞 Support
+
+- **Issues:** [GitHub Issues](https://github.com/kamera-linux/vogel-video-analyzer/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/kamera-linux/vogel-video-analyzer/discussions)
+
+---
+
+**Made with ❤️ by the Vogel-Kamera-Linux Team**