seavision-python 0.1.1__py3-none-any.whl

seavision/resources/default.yaml

@@ -0,0 +1,139 @@
+# =============================================================================
+# Buoy Detection Pipeline - Default Configuration
+# =============================================================================
+#
+# This file contains all configurable options for the detection pipeline.
+# Copy this file and modify as needed for different experiments.
+#
+# Usage:
+#   seavision --config config/default.yaml --input ./footage/
+#   seavision --config config/default.yaml --min-area 200  # CLI overrides
+#
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Input Options
+# -----------------------------------------------------------------------------
+
+input:
+  # Path to video file or directory (can be overridden via CLI --input)
+  # path: "./footage/"
+  
+  # Glob pattern for matching videos in a directory
+  pattern: "*.ts"
+  
+  # Source type: "local" or "s3"
+  source_type: "local"
+  
+  # S3-specific options (only used when source_type is "s3")
+  s3:
+    bucket: ""
+    prefix: ""
+    profile_name: ""  # AWS SSO profile name (e.g., "m3b-detector")
+  
+  # Process every Nth frame (1 = all frames, 5 = every 5th frame)
+  frame_skip: 1
+
+# -----------------------------------------------------------------------------
+# Output Options
+# -----------------------------------------------------------------------------
+
+output:
+  # Directory where detection CSV files will be saved
+  directory: "./output"
+  
+  # Output mode: "per_video" or "single"
+  #   per_video: Create one CSV per video (e.g., video1_detections.csv)
+  #   single: All detections in one CSV file
+  mode: "per_video"
+  
+  # Filename for single_file mode (ignored in per_video mode)
+  single_file_name: "detections.csv"
+  
+  # Whether to overwrite existing output files
+  # Set to true to replace existing files, false to raise an error
+  overwrite: false
+
+# -----------------------------------------------------------------------------
+# Pipeline Options
+# -----------------------------------------------------------------------------
+
+# Resume mode: skip videos that already have output CSV files
+# Useful for continuing interrupted processing runs
+resume: false
+
+# -----------------------------------------------------------------------------
+# Detector Configuration
+# -----------------------------------------------------------------------------
+
+detector:
+  # Detector type (currently only "motion" is implemented)
+  type: "motion"
+  
+  # Detector-specific configuration
+  config:
+    # --- Motion Detection Options ---
+    
+    # Enable/disable frame stabilisation (compensates for buoy sway)
+    stabilisation_enabled: true
+    
+    # Minimum contour area in pixels (smaller = more sensitive, more noise)
+    min_area: 500
+    
+    # Maximum contour area in pixels (larger areas are likely not fish)
+    max_area: 5000
+    
+    # Morphological operation kernel size (for noise cleanup)
+    morph_kernel_size: 5
+    
+    # Number of morphological operation iterations
+    morph_iterations: 2
+    
+    # --- Persistence Tracking Options ---
+    
+    # Enable persistence filtering (require objects to persist across frames)
+    persistence_enabled: true
+    
+    # Minimum frames an object must persist before being reported
+    min_persistence: 3
+    
+    # Maximum frames an object can be missing before track is dropped
+    max_frames_missing: 5
+    
+    # IoU threshold for matching detections between frames
+    iou_threshold: 0.3
+    
+    # --- Stabiliser Options ---
+    stabiliser:
+      # Feature detector type: "ORB" or "AKAZE"
+      feature_detector: "ORB"
+      
+      # Maximum number of features to detect per frame
+      max_features: 500
+      
+      # Lowe's ratio test threshold for feature matching (0.0 - 1.0)
+      # Lower = stricter matching, fewer but better matches
+      match_ratio: 0.75
+      
+      # Minimum number of feature matches required for homography
+      min_matches: 10
+      
+      # RANSAC reprojection threshold for outlier rejection
+      ransac_threshold: 5.0
+    
+    # --- Background Model Options ---
+    background:
+      # Number of frames used to build the background model
+      # Higher = more stable but slower to adapt
+      history: 600
+      
+      # Variance threshold for foreground classification
+      # Lower = more sensitive to changes
+      var_threshold: 16.0
+      
+      # Whether to detect and mark shadows
+      detect_shadows: true
+      
+      # Learning rate for background model adaptation
+      # -1 = automatic, or 0.0-1.0 where higher = faster adaptation
+      learning_rate: -1.0

seavision/run_edge.py

@@ -0,0 +1,96 @@
+"""
+CLI entry point for the SeaVision edge runtime.
+
+Usage:
+    seavision-edge                           # Use artifact in current directory
+    seavision-edge --artifact-dir ./artifact
+    seavision-edge --source 0                # Camera 0
+    seavision-edge --source video.mp4        # Video file
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _load_runtime_class():
+    """Import the runtime only when startup validation has passed."""
+    from seavision.edge import EdgeRuntime
+
+    return EdgeRuntime
+
+
+def _resolve_artifact_dir(path: str, manifest_filename: str) -> str:
+    """Resolve artifact directory, auto-selecting a nested artifact folder."""
+    artifact_dir = Path(path)
+    if not artifact_dir.exists() or not artifact_dir.is_dir():
+        return path
+
+    if (artifact_dir / manifest_filename).exists():
+        return str(artifact_dir)
+
+    nested_artifact_dir = artifact_dir / "artifact"
+    if (nested_artifact_dir / manifest_filename).exists():
+        return str(nested_artifact_dir)
+
+    return str(artifact_dir)
+
+
+def main() -> int:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        prog="seavision-edge",
+        description="SeaVision edge inference runtime",
+    )
+    parser.add_argument(
+        "--artifact-dir", default=".",
+        help="Path to the exported model artifact directory (default: current directory)",
+    )
+    parser.add_argument(
+        "--source", default=None,
+        help="Override video source (camera index or file path)",
+    )
+    parser.add_argument(
+        "--conf", type=float, default=None,
+        help="Override confidence threshold",
+    )
+    parser.add_argument(
+        "--frame-skip", type=int, default=None,
+        help="Override frame skip",
+    )
+
+    args = parser.parse_args()
+
+    from seavision.edge import EdgeConfig
+    from seavision.edge.config import ARTIFACT_MANIFEST_FILENAME
+
+    resolved_artifact_dir = _resolve_artifact_dir(
+        args.artifact_dir, ARTIFACT_MANIFEST_FILENAME
+    )
+
+    try:
+        config = EdgeConfig.from_artifact_dir(resolved_artifact_dir)
+    except FileNotFoundError:
+        print(
+            "ERROR: Artifact directory is incomplete or missing required files: "
+            f"{args.artifact_dir}"
+        )
+        print("Run seavision-export first to create an edge artifact directory.")
+        return 1
+
+    # Apply CLI overrides
+    if args.source is not None:
+        config.source = args.source
+    if args.conf is not None:
+        config.conf_threshold = args.conf
+    if args.frame_skip is not None:
+        config.frame_skip = args.frame_skip
+
+    EdgeRuntime = _load_runtime_class()
+    runtime = EdgeRuntime(config)
+    runtime.run()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

seavision/run_export.py

@@ -0,0 +1,176 @@
+"""
+CLI entry point for model export and edge artifact creation.
+
+Usage:
+    seavision-export --weights models/fish.pt --output ./deployment
+    seavision-export --weights models/fish.pt --imgsz 320 --target onnx
+"""
+
+import argparse
+import logging
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def parse_args():
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        prog="seavision-export",
+        description="Export a trained YOLO model for edge deployment",
+    )
+
+    parser.add_argument(
+        "--weights", required=True,
+        help="Path to the trained .pt weights file",
+    )
+    parser.add_argument(
+        "--output", default="./export",
+        help="Output directory for exported model and edge artifact (default: ./export)",
+    )
+    parser.add_argument(
+        "--target", default="onnx",
+        choices=["onnx", "tflite", "ncnn", "torchscript"],
+        help="Export target format (default: onnx)",
+    )
+    parser.add_argument(
+        "--imgsz", type=int, default=640,
+        help="Input image size (default: 640)",
+    )
+    parser.add_argument(
+        "--half", action="store_true",
+        help="Use float16 quantisation",
+    )
+    parser.add_argument(
+        "--int8", action="store_true",
+        help="Use int8 quantisation",
+    )
+    parser.add_argument(
+        "--no-validate", action="store_true",
+        help="Skip export validation",
+    )
+    parser.add_argument(
+        "--device", default="cpu",
+        help="Device for export (default: cpu)",
+    )
+    parser.add_argument(
+        "--conf", type=float, default=0.25,
+        help="Default confidence threshold for edge config (default: 0.25)",
+    )
+    parser.add_argument(
+        "--frame-skip", type=int, default=1,
+        help="Default frame skip for edge config (default: 1)",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true",
+        help="Enable debug logging",
+    )
+
+    return parser.parse_args()
+
+
+def main() -> int:
+    """Main entry point."""
+    args = parse_args()
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    from seavision.engine.export import (
+        ExportConfig,
+        ExportTarget,
+        ModelExporter,
+    )
+
+    # Map string target to enum
+    target_map = {
+        "onnx": ExportTarget.ONNX,
+        "tflite": ExportTarget.TFLITE,
+        "ncnn": ExportTarget.NCNN,
+        "torchscript": ExportTarget.TORCHSCRIPT,
+    }
+
+    config = ExportConfig(
+        weights_path=args.weights,
+        output_dir=args.output,
+        target=target_map[args.target],
+        imgsz=args.imgsz,
+        half=args.half,
+        int8=args.int8,
+        validate=not args.no_validate,
+        device=args.device,
+    )
+
+    # --- Export ---
+    print(f"Exporting {args.weights} to {args.target.upper()}...")
+    exporter = ModelExporter(config)
+    result = exporter.export()
+
+    if not result.success:
+        print(f"\nERROR: Export failed: {result.error}")
+        return 1
+
+    print(f"\nExport successful:")
+    print(f"  Model: {result.exported_path}")
+    print(f"  Size:  {result.model_size_mb:.1f} MB")
+    print(f"  Classes: {result.num_classes}")
+    if result.class_names:
+        names = ", ".join(
+            f"{k}={v}" for k, v in sorted(result.class_names.items())[:10]
+        )
+        if len(result.class_names) > 10:
+            names += f", ... ({len(result.class_names)} total)"
+        print(f"  Labels: {names}")
+
+    if result.validation:
+        status = "PASSED" if result.validation.passed else "FAILED"
+        print(f"  Validation: {status}")
+        print(f"    {result.validation.details}")
+
+    from pathlib import Path
+    from seavision.edge.bundle import ArtifactBuilder
+    from seavision.edge.config import EdgeConfig
+
+    exported_path = Path(result.exported_path)
+    if exported_path.is_dir():
+        metadata_path = exported_path / "export_metadata.json"
+    else:
+        metadata_path = exported_path.with_suffix(".json")
+
+    if not metadata_path.exists():
+        print(f"\nWARNING: Metadata file not found at {metadata_path}")
+        print("Skipping artifact creation.")
+        return 0
+
+    edge_config = EdgeConfig(
+        conf_threshold=args.conf,
+        frame_skip=args.frame_skip,
+    )
+
+    artifact_dir = Path(args.output) / "artifact"
+    print(f"\nCreating edge artifact: {artifact_dir}")
+
+    builder = ArtifactBuilder(
+        exported_model_path=result.exported_path,
+        export_metadata_path=str(metadata_path),
+        output_dir=str(artifact_dir),
+        edge_config=edge_config,
+    )
+    artifact_path = builder.build()
+
+    print(f"\nArtifact created: {artifact_path}")
+    print("\nDeployment instructions:")
+    print(f"  1. Copy the '{artifact_dir.name}' directory to your Pi:")
+    print(f"     scp -r {artifact_dir} pi@<pi-ip>:~/")
+    print("  2. Install or update the SeaVision wheel on the Pi:")
+    print("     python3 -m pip install '<seavision-wheel>[edge]'")
+    print("  3. Run the detector:")
+    print(f"     seavision-edge --artifact-dir ~/{artifact_dir.name}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())