seavision-python 0.1.1__py3-none-any.whl

seavision/run_pipeline.py

@@ -0,0 +1,388 @@
+#!/usr/bin/env python
+"""Command line interface for the buoy detection pipeline."""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from .defaults import write_default_pipeline_config
+from .engine import (
+    discover_local_videos,
+    discover_s3_videos,
+    OutputMode,
+)
+from .pipeline import (
+    DetectionPipeline,
+    PipelineConfig,
+    InputConfig,
+    setup_logging,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command line arguments."""
+    
+    parser = argparse.ArgumentParser(
+        description="Buoy detection pipeline - object detection in buoy footage.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Example usage:
+  # Process local videos
+    seavision --input ./footage/ --output ./results/
+
+  # Process a single video
+    seavision --input ./footage/video.ts --output ./results/
+
+  # Write the packaged default config to a local file
+    seavision --write-default-config ./seavision-config.yaml
+
+  # Use a config file
+    seavision --config ./seavision-config.yaml
+
+  # Dry run (scan without processing)
+    seavision --input ./footage/ --dry-run
+
+  # Resume interrupted processing
+    seavision --input ./footage/ --output ./results/ --resume
+
+  # Quick preview (every 10th frame)
+    seavision --input ./footage/ --frame-skip 10
+        """,
+    )
+
+    # Input options
+    input_group = parser.add_argument_group("Input options")
+    input_group.add_argument(
+        "--input", "-i",
+        type=str,
+        help="Path to video file or directory containing videos.",
+    )
+    input_group.add_argument(
+        "--pattern", "-p",
+        type=str,
+        default="*.ts",
+        help="Glob pattern for matching videos in a directory (default: *.ts).",
+    )
+    input_group.add_argument(
+        "--source-type",
+        type=str,
+        choices=["local", "s3"],
+        default=None,
+        help="Video source type (default: local). Can be set in config file.",
+    )
+    input_group.add_argument(
+        "--s3-bucket",
+        type=str,
+        help="S3 bucket name (for s3 source type).",
+    )
+    input_group.add_argument(
+        "--s3-prefix",
+        type=str,
+        help="S3 prefix/path (for s3 source type).",
+    )
+    input_group.add_argument(
+        "--s3-profile",
+        type=str,
+        help="AWS SSO profile name (for s3 source type).",
+    )
+
+    # Output options
+    output_group = parser.add_argument_group("Output options")
+    output_group.add_argument(
+        "--output", "-o",
+        type=str,
+        default="./output",
+        help="Output directory for detection CSV files (default: ./output).",
+    )
+    output_group.add_argument(
+        "--single-file",
+        action="store_true",
+        help="Write all detections to a single CSV file instead of per-video.",
+    )
+    output_group.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Overwrite existing output files.",
+    )
+
+    # Processing options
+    proc_group = parser.add_argument_group("Processing options")
+    proc_group.add_argument(
+        "--frame-skip",
+        type=int,
+        default=1,
+        help="Process every Nth frame (default: 1, all frames).",
+    )
+    proc_group.add_argument(
+        "--resume",
+        action="store_true",
+        help="Skip videos that already have output files.",
+    )
+    proc_group.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Scan videos and report statistics without processing.",
+    )
+
+    # Detector options
+    det_group = parser.add_argument_group("Detector options")
+    det_group.add_argument(
+        "--detector",
+        type=str,
+        default="motion",
+        help="Detector type to use (default: motion).",
+    )
+    det_group.add_argument(
+        "--min-area",
+        type=int,
+        help="Minimum contour area in pixels (motion detector).",
+    )
+    det_group.add_argument(
+        "--max-area",
+        type=int,
+        help="Maximum contour area in pixels (motion detector).",
+    )
+    det_group.add_argument(
+        "--no-stabilisation",
+        action="store_true",
+        help="Disable frame stabilisation (motion detector).",
+    )
+
+    # Config file
+    parser.add_argument(
+        "--config", "-c",
+        type=str,
+        help="Path to YAML configuration file. CLI args override config file values.",
+    )
+    parser.add_argument(
+        "--write-default-config",
+        type=str,
+        help=(
+            "Write the packaged default YAML configuration to the given path "
+            "and exit."
+        ),
+    )
+    parser.add_argument(
+        "--force-write-default-config",
+        action="store_true",
+        help="Allow --write-default-config to overwrite an existing file.",
+    )
+
+    # Logging
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Enable verbose (debug) logging.",
+    )
+    parser.add_argument(
+        "--quiet", "-q",
+        action="store_true",
+        help="Suppress info logging, only show warnings and errors.",
+    )
+
+    return parser.parse_args()
+
+
+def load_config_file(config_path: str) -> dict:
+    """
+    Load configuration from a YAML file.
+
+    Args:
+        config_path: Path to the YAML configuration file.
+
+    Returns:
+        Dictionary with configuration values.
+
+    Raises:
+        FileNotFoundError: If the config file doesn't exist.
+    """
+    path = Path(config_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+
+    with open(path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+def build_config(args: argparse.Namespace) -> PipelineConfig:
+    """
+    Build PipelineConfig from CLI arguments and optional config file.
+
+    Precendence: CLI args > config file > defaults.
+
+    Args:
+        args: Parsed command line arguments.
+    
+    Returns:
+        PipelineConfig object with merged configuration.
+    """
+    # Start with defaults or config file
+    if args.config:
+        config_data = load_config_file(args.config)
+        config = PipelineConfig.from_dict(config_data)
+    else:
+        config = PipelineConfig()
+
+    # Override with CLI arguments
+    if args.frame_skip != 1:
+        config.input = InputConfig(frame_skip=args.frame_skip)
+
+    if args.output:
+        config.output.output_dir = args.output
+    if args.single_file:
+        config.output.output_mode = OutputMode.SINGLE_FILE
+    if args.overwrite:
+        config.output.overwrite = True
+
+    if args.resume:
+        config.resume = True
+
+    # Detector config overrides
+    if args.detector:
+        config.detector.type = args.detector
+
+    detector_overrides = {}
+    if args.min_area is not None:
+        detector_overrides["min_area"] = args.min_area
+    if args.max_area is not None:
+        detector_overrides["max_area"] = args.max_area
+    if args.no_stabilisation:
+        detector_overrides["stabilisation_enabled"] = False
+
+    if detector_overrides:
+        # Merge with existing detector config
+        config.detector.config.update(detector_overrides)
+
+    return config
+
+
+def discover_sources(args: argparse.Namespace, config_data: Optional[dict] = None):
+    """
+    Discover video sources based on CLI arguments and config file.
+
+    Args:
+        args: Parsed command-line arguments.
+        config_data: Configuration data from YAML file (optional).
+
+    Returns:
+        List of VideoSource instances.
+
+    Raises:
+        ValueError: If no input path is specified.
+    """
+    config_data = config_data or {}
+    input_config = config_data.get("input", {})
+    s3_config = input_config.get("s3", {})
+    
+    # Determine input path (CLI takes precedence)
+    input_path = args.input or input_config.get("path")
+    if not input_path:
+        raise ValueError(
+            "No input specified. Use --input or set input.path in config file."
+        )
+    
+    # Determine source type (CLI takes precedence)
+    source_type = args.source_type or input_config.get("source_type", "local")
+    
+    # Determine pattern (CLI takes precedence)
+    pattern = args.pattern if args.pattern != "*.ts" else input_config.get("pattern", "*.ts")
+
+    if source_type == "local":
+        return discover_local_videos(input_path, pattern)
+    elif source_type == "s3":
+        # Get S3 settings (CLI takes precedence over config)
+        bucket = args.s3_bucket or s3_config.get("bucket") or input_path
+        prefix = args.s3_prefix or s3_config.get("prefix", "")
+        profile = args.s3_profile or s3_config.get("profile_name")
+        
+        return discover_s3_videos(
+            bucket=bucket,
+            prefix=prefix,
+            pattern=pattern,
+            profile_name=profile
+        )
+    else:
+        raise ValueError(f"Unknown source type: {source_type}")
+    
+
+def main() -> int:
+    """
+    Main entry point for the CLI.
+
+    Returns:
+        Exit code (0 for success, non-zero for errors).
+    """
+    args = parse_args()
+
+    # Set up logging
+    if args.verbose:
+        log_level = logging.DEBUG
+    elif args.quiet:
+        log_level = logging.WARNING
+    else:
+        log_level = logging.INFO
+    setup_logging(log_level)
+
+    logger = logging.getLogger(__name__)
+
+    if args.write_default_config:
+        try:
+            output_path = write_default_pipeline_config(
+                args.write_default_config,
+                overwrite=args.force_write_default_config,
+            )
+        except FileExistsError as e:
+            print(str(e))
+            print(
+                "Use --force-write-default-config to overwrite the existing file."
+            )
+            return 1
+
+        print(f"Default configuration written to: {output_path}")
+        return 0
+
+    try:
+        # Load config file if specified
+        config_data = {}
+        if args.config:
+            config_data = load_config_file(args.config)
+        
+        # Build configuration
+        config = build_config(args)
+
+        # Discover video sources
+        sources = discover_sources(args, config_data)
+        logger.info("Discovered %d video source(s).", len(sources))
+
+        # Create and run pipeline
+        pipeline = DetectionPipeline(config)
+        result = pipeline.process_sources(sources, dry_run=args.dry_run)
+
+        # Print results
+        print()
+        print(result.summary())
+
+        # Return appropriate exit code
+        if hasattr(result, "videos_failed") and result.videos_failed > 0: # pyright: ignore[reportAttributeAccessIssue]
+            return 1  # Some videos failed
+        return 0
+
+    except FileNotFoundError as e:
+        logger.error(str(e))
+        return 1
+    except ValueError as e:
+        logger.error(str(e))
+        return 1
+    except KeyboardInterrupt:
+        logger.info("Interrupted by user.")
+        return 130
+    except Exception as e: # pylint: disable=broad-exception-caught
+        logger.exception("Unexpected error: %s", e)
+        return 1
+
+if __name__ == "__main__":
+    sys.exit(main())

seavision_python-0.1.1.dist-info/METADATA

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: seavision-python
+Version: 0.1.1
+Summary: Human-in-the-loop Computer Vision for Marine Environments
+Author: Mario Lambrette
+License: Proprietary
+Project-URL: Homepage, https://github.com/mariolambrette/SeaVision
+Project-URL: Documentation, https://github.com/mariolambrette/SeaVision/tree/Main/docs
+Project-URL: Source, https://github.com/mariolambrette/SeaVision
+Project-URL: Issues, https://github.com/mariolambrette/SeaVision/issues
+Keywords: computer-vision,detection,marine,SAM3
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy<2.0,>=1.21
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.60
+Provides-Extra: s3
+Requires-Dist: boto3>=1.26; extra == "s3"
+Provides-Extra: gui
+Requires-Dist: boto3>=1.26; extra == "gui"
+Requires-Dist: PySide6<6.9,>=6.5; extra == "gui"
+Requires-Dist: psutil>=5.9; extra == "gui"
+Provides-Extra: edge
+Requires-Dist: onnxruntime>=1.16; extra == "edge"
+Provides-Extra: export
+Requires-Dist: onnxruntime>=1.16; extra == "export"
+Requires-Dist: ultralytics>=8.3.237; extra == "export"
+Provides-Extra: sam3
+Requires-Dist: pillow>=10.0; extra == "sam3"
+Requires-Dist: torch>=2.0; extra == "sam3"
+Requires-Dist: torchvision>=0.20; extra == "sam3"
+Requires-Dist: transformers>=4.47; extra == "sam3"
+Requires-Dist: ultralytics>=8.3.237; extra == "sam3"
+Provides-Extra: all
+Requires-Dist: boto3>=1.26; extra == "all"
+Requires-Dist: onnxruntime>=1.16; extra == "all"
+Requires-Dist: pillow>=10.0; extra == "all"
+Requires-Dist: psutil>=5.9; extra == "all"
+Requires-Dist: PySide6<6.9,>=6.5; extra == "all"
+Requires-Dist: torch>=2.0; extra == "all"
+Requires-Dist: torchvision>=0.20; extra == "all"
+Requires-Dist: transformers>=4.47; extra == "all"
+Requires-Dist: ultralytics>=8.3.237; extra == "all"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+
+<p align="left">
+  <img src="https://raw.githubusercontent.com/mariolambrette/SeaVision/Main/assets/seavision_logo.jpg" alt="Logo" width="200"/>
+</p>
+
+# SeaVision
+
+## Human-in-the-loop Computer Vision for Marine Environments
+
+> [!WARNING]
+> Documentation is currently out of date.
+> The packaging, release, and edge-deployment flows have changed recently, and
+> some instructions in this README and the linked docs may still describe older
+> clone-first or pre-release workflows. Treat the published release artifacts
+> and current CLI behavior as the source of truth until the docs are refreshed.
+
+SeaVision offers a practical computer vision workflow for marine monitoring. It supports the development of accurate, 
+custom detection models for specific deployment scenarios. The main workflow is:
+
+1. Deploy a generic detector (e.g. motion detection, SAM3-based semantic detection, etc.) on recorded footage.
+2. Use the provided GUI to validate and refine detections into a training dataset.
+3. Train a custom YOLO detection model.
+4. Deploy the trained model on a desktop workstation or edge device with the provided export functionality.
+
+If you are new to the project, start with the [Start Here guide](./docs/Start_Here.md).
+
+## Start Here (New Users)
+
+If you are not a computer vision specialist, use this short path first:
+
+1. Read the [Start Here guide](./docs/Start_Here.md) for a plain-language workflow and glossary.
+2. Install SeaVision in GUI mode: `python -m pip install ".[gui]"`.
+3. Run `seavision-gui` and create a new session with `Ctrl+N`.
+4. Follow the GUI [Getting Started guide](./docs/gui/Getting%20started.md).
+
+## Installation
+
+### Prerequisites
+
+- Python 3.12
+- pip
+
+### Install from a cloned repository
+
+Before installing the package, you must currently clone this repository. Run the following in a
+bash terminal:
+
+```bash
+git clone https://github.com/mariolambrette/SeaVision
+cd SeaVision
+```
+
+It is recommended to install SeaVision in a dedicated environment. If you are a [conda](https://www.anaconda.com/docs/getting-started/anaconda/install/overview) user, run
+the following:
+
+```bash
+conda create seavision
+conda activate seavision
+```
+
+You can now install SeaVision using pip:
+
+```bash
+pip install ".[<extras>]"
+```
+
+SeaVision can be installed in various modes, each of which supports different modes of functionality. See below for a full 
+description of all installation modes.
+
+### Install Matrix (User Types)
+
+Use the install command that matches your use case.
+
+| User type | Install command | Primary CLI command(s) |
+|---|---|---|
+| Detection-only users (local videos) | `python -m pip install .` | `seavision` |
+| Detection users with videos in S3 bucket | `python -m pip install ".[s3]"` | `seavision` |
+| GUI users (includes S3 support) | `python -m pip install ".[gui]"` | `seavision-gui` |
+| Edge device operators (runtime only) | `python -m pip install ".[edge]"` | `seavision-edge` |
+| Export users (prepare edge artifacts) | `python -m pip install ".[export]"` | `seavision-export` |
+| Advanced/full users | `python -m pip install ".[all]"` | `seavision`, `seavision-gui`, `seavision-export`, `seavision-edge` |
+
+Most users should use either `python -m pip install ".[gui]"` for desktop-only usage or `python -m pip install ".[all]"` if they are
+also likely to use edge deployment functionality. Other installation methods may provide lighter dependencies in specific scenarios.
+
+You can verify your installation by running [test commands](#install-verification)
+
+### Development install
+
+```bash
+python -m venv venv
+venv\Scripts\activate.bat
+python -m pip install -e ".[dev]"
+```
+
+For release/distribution policy and compatibility targets, see:
+
+- [Distribution and compatibility policy](./docs/release/Distribution_and_Compatibility.md)
+
+### Optional GPU acceleration
+
+The above install allows you to run all SeaVision functionality but does not
+provide support for GPU-accelerated processing. Some methods (e.g. SAM3-based
+detection) will be significantly faster if a GPU is available. You will need to
+install GPU-specific dependencies manually based on your hardware.
+
+For example, to run on an NVIDIA RTX 5090 GPU with cuda 13 you could install
+the following:
+
+```bash
+pip install torch>=2.9.0 torchvision>=0.20.0 --index-url https://download.pytorch.org/whl/cu130 --force-reinstall
+```
+You can find more information on PyTorch compatibility
+[here](https://pytorch.org/get-started/locally/).
+
+### AWS S3 Access (Optional)
+
+The pipeline supports streaming video directly from AWS. In order to access this
+feature you will need to configure an AWS SSO profile. For more information on
+how to do this and integrate AWS streaming into the SeaVision workflow, see the
+[AWS setup documentation](./docs/AWS_SETUP.md)
+
+## Install verification
+
+Run the command that matches your installed mode:
+
+```bash
+# Detection CLI
+seavision --help
+
+# GUI
+seavision-gui
+
+# Export CLI
+seavision-export --help
+
+# Edge CLI
+seavision-edge --help
+```
+
+## Quick start
+
+### 1. Run the detection pipeline
+
+The full detection pipeline can be run with a CLI command, which can optionally be configured
+with a [YAML file](./config/default.yaml)
+
+```bash
+# Local files
+seavision --input ./data/footage/ --output ./results/
+
+# With config file
+seavision --config config/default.yaml
+```
+
+### 2. Launch the GUI
+
+```bash
+seavision-gui
+```
+
+### 3. Export for edge deployment
+
+```bash
+seavision-export --weights models/fish.pt --output ./deployment --target onnx
+```
+
+### 4. Run on an edge device
+
+```bash
+seavision-edge --artifact-dir ./deployment/artifact
+```
+
+## Troubleshooting quick checks
+
+| Problem | Likely cause | Quick check | Fix |
+|---|---|---|---|
+| `seavision: command not found` | Package not installed in active environment | `python -m pip show seavision` | Activate the right environment and reinstall using the install matrix |
+| `seavision-gui: command not found` | GUI extra not installed | `python -m pip show PySide6` | `python -m pip install ".[gui]"` |
+| `seavision-edge: command not found` | Edge extra not installed | `python -m pip show onnxruntime` | `python -m pip install ".[edge]"` |
+| Import error for `boto3` when using S3 | S3 dependency missing | `python -m pip show boto3` | `python -m pip install ".[s3]"` or `python -m pip install ".[gui]"` |
+| GUI starts but S3 login fails | AWS credentials/session not configured | `aws sts get-caller-identity` | Run `aws sso login --profile <profile-name>` and retry |
+| Edge run fails at startup validation | Artifact dir incomplete or invalid | `seavision-edge --artifact-dir <path>` output | Re-run `seavision-export` and copy the full artifact directory again |
+
+## Configuration
+
+The SeaVision pipeline can be fully customised using YAML config files. For
+a documented example of a config file see the
+[default configuration](./config/default.yaml)
+
+
+## Edge Deployment
+
+Users may wish to deploy models developed or refined using SeaVision to an edge
+device. Full support is provided for deploying trained model weight files
+(`*.pt`) on Raspberry Pi.
+
+Edge deployment creates SeaVision detection files directly on the Pi which may
+save compute time, power and data transfer requirements. Users can optionally
+export periodic validation clips alongside the detections. See below for 
+detailed documentation:
+
+If you are new to the deployment workflow, use this order:
+
+1. [Edge deployment overview](./docs/edge/README.md)
+2. [Concepts and Terms](./docs/edge/Concepts%20and%20Terms.md)
+3. [Prerequisites Checklist](./docs/edge/Prerequisites%20Checklist.md)
+4. [Operator Quickstart](./docs/edge/Operator%20Quickstart.md)
+5. [Troubleshooting](./docs/edge/Troubleshooting.md)
+
+Use the technical references only when you are preparing the deployment files
+or troubleshooting the package structure:
+
+- [Deploy to Raspberry Pi](./docs/edge/Deploy%20to%20Raspberry%20Pi.md)
+- [Troubleshooting](./docs/edge/Troubleshooting.md)
+- [Wheel runtime workflow](./docs/edge/Wheel%20Runtime.md)
+- [Model artifact layout](./docs/edge/Model%20Artifacts.md)
+- [Rollback runbook](./docs/edge/Rollback%20Runbook.md)
+
+## Documentation
+
+- [Start Here guide](./docs/Start_Here.md)
+- [Class and API reference](./docs/Class_reference.md)
+- [Architecture and class diagrams](./docs/Class_diagram.md)
+- [AWS setup guide](./docs/AWS_SETUP.md)
+- [Edge deployment docs](./docs/edge/README.md)
+- [GUI docs](./docs/gui/README.md)
+
+## Project Status
+
+Note that this project is under active development and features may not yet
+work as intended.