seavision 1.0.0__tar.gz

seavision-1.0.0/.claude/CLAUDE.md

@@ -0,0 +1,5 @@
+# Claude Code Project Instructions
+
+<!-- Imports AGENTS.md, which contains agent roles, behavioral rules, and coding constraints for this project. -->
+
+@../AGENTS.md

seavision-1.0.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  # Enable version updates for GitHub Actions
+  - package-ecosystem: "github-actions"
+    # Workflow files stored in the default location of `.github/workflows`
+    # You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.
+    directory: "/"
+    schedule:
+      interval: "weekly"

seavision-1.0.0/.github/workflows/ci.yaml

@@ -0,0 +1,160 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - develop
+  pull_request:
+    branches:
+      - develop
+
+jobs:
+  checkout:
+    runs-on: ubuntu-latest
+    outputs:
+      repo-cache-key: repo-${{ github.sha }}
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # Ensures we get commit history for diffing
+
+      - name: 🔄 Cache repository
+        uses: actions/cache@v5
+        with:
+          path: . # Cache the entire repo
+          key: repo-${{ github.sha }}
+
+  changed-files:
+    needs: checkout
+    runs-on: ubuntu-latest
+    outputs:
+      changed_files: ${{ steps.changed-python-files.outputs.all_changed_files }}
+    steps:
+      - name: 🔄 Restore repository from cache
+        uses: actions/cache@v5
+        with:
+          path: .
+          key: repo-${{ github.sha }}
+
+      - name: 🔍 Get changed files
+        id: changed-python-files
+        uses: tj-actions/changed-files@v47
+        with:
+          files: |
+            **/*.py
+            **/*.pyi
+
+  ruff-linter:
+    needs: changed-files
+    runs-on: ubuntu-latest
+    if: ${{ needs.changed-files.outputs.changed_files != '' }}
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: 🔄 Restore repository from cache
+        uses: actions/cache@v5
+        with:
+          path: .
+          key: repo-${{ github.sha }}
+
+      - uses: astral-sh/ruff-action@v3
+        name: ✨ Lint with Ruff (only changed files)
+        with:
+          version: "latest"
+          src: ${{ needs.changed-files.outputs.changed_files }}
+          args: check --output-format=github
+
+  ruff-format:
+    needs: changed-files
+    runs-on: ubuntu-latest
+    if: ${{ needs.changed-files.outputs.changed_files != '' }}
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: 🔄 Restore repository from cache
+        uses: actions/cache@v5
+        with:
+          path: .
+          key: repo-${{ github.sha }}
+
+      - uses: astral-sh/ruff-action@v3
+        name: 📝 Format with Ruff (only changed files)
+        with:
+          version: "latest"
+          src: ${{ needs.changed-files.outputs.changed_files }}
+          args: "format --diff"
+
+  pylint:
+    needs: changed-files
+    runs-on: ubuntu-latest
+    if: ${{ needs.changed-files.outputs.changed_files != '' }}
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: 🔄 Restore repository from cache
+        uses: actions/cache@v5
+        with:
+          path: .
+          key: repo-${{ github.sha }}
+
+      - name: 🛠️ Install the latest version of uv and set the python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: 🦾 Install the project
+        run: uv sync --all-extras
+
+      - name: 🦾 Install pylint
+        run: uv pip install pylint
+
+      - name: 🔍 Run Pylint
+        run: uv run pylint ${{ needs.changed-files.outputs.changed_files }}
+
+  sonarqube:
+    needs:
+      - checkout # Needs full repo
+      - changed-files
+      - ruff-linter
+      - ruff-format
+      - pylint
+    runs-on: ubuntu-latest
+    if: ${{ needs.changed-files.outputs.changed_files != '' }}
+    steps:
+      - name: 🔄 Restore repository from cache
+        uses: actions/cache@v5
+        with:
+          path: .
+          key: repo-${{ github.sha }}
+
+      - name: 📥 Install ffmpeg
+        uses: AnimMouse/setup-ffmpeg@v1
+
+      - name: 🛠️ Install the latest version of uv and set the python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: 🦾 Install the project
+        run: uv sync
+
+      - name: 🧪 Run pytest with coverage
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          WANDB_API_KEY: ${{ secrets.WANDB_API_KEY }}
+        run: uv run pytest --cov-report=xml
+
+      - name: 🔎 SonarQube Cloud Scan (Full Repo)
+        uses: SonarSource/sonarqube-scan-action@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+
+      - name: 🧹 Minimize uv cache
+        run: uv cache prune --ci

seavision-1.0.0/.github/workflows/docs.yaml

@@ -0,0 +1,40 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - develop
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      DEPLOY: true
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v5
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install dependencies and deploy docs
+        run: |
+          uv sync --all-extras
+          uv run mkdocs gh-deploy --force

seavision-1.0.0/.github/workflows/publish.yaml

@@ -0,0 +1,64 @@
+name: Publish
+
+on:
+  pull_request:
+    branches: [develop]
+    paths:
+      # Re-run packaging checks when the workflow, packaging config,
+      # or package source changes.
+      - ".github/workflows/publish.yaml"
+      - "pyproject.toml"
+      - "seavision/**"
+
+  # Only publish when a GitHub release is published.
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  # Build a universal wheel (py3-none-any) and the source distribution.
+  # seavision is pure Python, so one wheel works on every platform / Python
+  # version that satisfies requires-python.
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.release.tag_name || github.sha }}
+          # hatch-vcs needs full git history to resolve the version from tags.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+
+  # Publish only on release, after the build artifacts exist.
+  publish:
+    needs: [build]
+    if: ${{ github.event_name == 'release' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    permissions:
+      # Required for trusted publishing to PyPI via GitHub OIDC.
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

seavision-1.0.0/.gitignore

@@ -0,0 +1,181 @@
+# vscode
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+!.vscode/launch.json
+
+# Models
+models/
+*.onnx
+*.engine
+*.pt
+
+# CSV files
+*.csv
+
+# MacOS
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Ruff
+.ruff_cache/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

seavision-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update
+    rev: v0.9.0
+    hooks:
+    -   id: pre-commit-update
+
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+        exclude: mkdocs.yml
+    -   id: check-added-large-files
+        args: ["--maxkb=1500"]
+    -   id: check-json
+    -   id: pretty-format-json
+        args: [--autofix, --no-sort-keys]
+        exclude: .*\.ipynb$
+    -   id: check-case-conflict
+    -   id: name-tests-test
+        args: [--pytest-test-first]
+
+-   repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+    -   id: gitleaks
+
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.15.9
+    hooks:
+      # Run the linter.
+    -   id: ruff
+        args: [--fix]
+    -   id: ruff-format
+        exclude: .*\.ipynb$
+
+-   repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v22.1.2
+    hooks:
+    -   id: clang-format
+        types_or: [c, c++, cuda]
+
+# vscode does not use python environment, so run tests manually
+# -   repo: local
+#     hooks:
+#       - id: pytest
+#         name: run unit tests
+#         entry: pytest
+#         language: system
+#         pass_filenames: false

seavision-1.0.0/.sonarlint/connectedMode.json

@@ -0,0 +1,4 @@
+{
+  "sonarCloudOrganization": "sea-ai",
+  "projectKey": "SEA-AI_seavision"
+}

seavision-1.0.0/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "charliermarsh.ruff",
+    "ms-python.pylint"
+  ],
+  "unwantedRecommendations": []
+}

seavision-1.0.0/.vscode/settings.json

@@ -0,0 +1,30 @@
+{
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.organizeImports": "explicit",
+      "source.fixAll.ruff": "explicit"
+    }
+  },
+  "sonarlint.connectedMode.project": {
+    "connectionId": "sea-ai",
+    "projectKey": "SEA-AI_seavision"
+  },
+  "python.testing.pytestArgs": [
+    "tests"
+  ],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true,
+  "pylint.ignorePatterns": [
+    "*test*.py"
+  ],
+  "files.exclude": {
+    "**/.mypy_cache": true,
+    "**/.pytest_cache": true,
+    "**/.ruff_cache": true
+  },
+  "emojisense.languages": {
+    "python": true
+  }
+}

seavision-1.0.0/AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS.md
+
+This file guides AI coding assistants (e.g. Claude Code, Cursor) when working in this repository.
+
+## Commands
+
+```bash
+# Install dependencies (use uv, not pip)
+uv sync                    # main + dev dependencies
+uv sync --all-extras       # include optional extras (e.g. fiftyone)
+
+# Linting and formatting
+uvx ruff check --fix       # lint and auto-fix
+uvx ruff format            # format code
+
+# Testing
+uv run pytest              # run all tests
+uv run pytest tests/path/to/test_file.py  # run a single test file
+uv run pytest -k "test_name"              # run tests matching a pattern
+uv run pytest --cov        # run with coverage (default in pytest.ini)
+
+# Documentation
+uvx mkdocs serve           # serve docs locally
+
+# Pre-commit hooks
+uvx pre-commit install     # install hooks
+uvx pre-commit run --all-files  # run all hooks manually
+
+# CLI (after install)
+seavision models list
+seavision inference <path>
+seavision calibration
+```
+
+## Architecture
+
+SeaVision is a Python computer vision library for maritime/naval applications (ship detection, thermal imaging, horizon detection, sensor fusion). It supports Python 3.9–3.12.
+
+### Module Overview
+
+- **`inference/`** — Core module. Model loading, preprocessing, postprocessing, and inference pipelines. Contains model implementations: AHOY (multi-modal), DAN (dual YOLO), HOLY, RAHI (region-based), SAHI (sliced), LouisNet, SeaYOLO. Supports TensorRT, ONNX2Torch, and TensorFlow backends.
+- **`io/`** — VideoReader/VideoWriter with multi-threaded queue-based reading. Handles webcam, RTSP, local files. `VideoFormatRegistry` allows extensible format handlers.
+- **`geometry/`** — Immutable pinhole `Camera` (intrinsics/pose) and `CameraGeometry` helpers in `pinhole.py`. Composite image/video utilities for multi-sensor layouts. Distance / JSON config types live in `distance.py`.
+- **`calibration/`** — FastAPI-based web UI for interactive camera extrinsic tuning (pitch/yaw/roll).
+- **`transforms/`** — Image/video processing: normalization, enhancement, color conversion.
+- **`sensorfusion/`** — Multi-sensor fusion: NMS and Weighted Boxes Fusion (WBF, the primary algorithm).
+- **`deployment/`** — Model format conversion: ONNX → TRT composition utilities.
+- **`cli/`** — Click-based CLI entry point (`seavision` command).
+- **`utils/`** — Logging, HuggingFace Hub downloads, ONNX utilities.
+- **`fiveone/`** — Optional FiftyOne dataset integration (excluded from coverage).
+- **`experimental/`** — Zoom and video embedding experiments.
+
+### Key Patterns
+
+**Inference pipeline:**
+```python
+output = postprocess(model.forward(preprocess(inputs)))
+```
+
+**Abstract base classes:** `Model` (all inference models), `Infer` (inference engine backends), `SensorFusion` (fusion algorithms).
+
+**Factory pattern:** `ModelFactory` loads models from HuggingFace Hub, local ONNX files, TensorRT engines, or W&B. Enum-based model variants select specific configurations.
+
+**Results datamodel:** Immutable dataclasses (`Results`, `Object`, `BBox`, `Horizon`, `Line`) with coordinate helpers (normalized ↔ absolute pixels), FiftyOne export, and drawing/visualization support.
+
+**Public API entry point:**
+```python
+import seavision as sv
+model = sv.load_model("ahoyv2n-MIX-b1")
+results = model(image)
+results.draw(image).show()
+```
+
+### Testing
+
+Tests mirror the source structure. Fixtures in `tests/conftest.py` provide sample `Results` with boats, ships, and horizon data. Test assets in `tests/assets/` include sensor configs (legacy/oceanus/standard). Some tests fetch images from GitHub; set a local asset folder env var for offline testing.
+
+- **`ffmpeg`** must be installed on the system (used by `av` / `ffmpeg-python`); without it, video-related tests and code paths can fail.
+- Some tests download models from **Hugging Face** or **Weights & Biases** and need **`HF_TOKEN`** and **`WANDB_API_KEY`**; those tests fail without the secrets, while the rest of the suite can still pass.
+
+Coverage excludes `fiveone/`, TensorRT code, and the HOLY model.
+
+### Code Style
+
+- Ruff enforces Google-style docstrings, 88-char line length, and 14 rule categories (D, E, F, W, ANN, B, TC, PTH, NPY, TID, SIM, I, PL, ERA).
+- Single-letter variable names are allowed for matrix conventions: `K` (camera intrinsics), `R` (rotation), `H` (homography), `B` (batch), `C` (channels), `W` (width), `G` (grayscale).
+- Heavy dependencies (torch, cv2, onnx) use lazy imports (import-outside-toplevel is allowed); type-only imports go in `TYPE_CHECKING` blocks.
+- Max 10 args/attributes per function or class.
+
+### CI
+
+The CI pipeline (`.github/workflows/ci.yaml`) detects changed files and runs Ruff, Pylint, SonarQube, and pytest only on affected code. PRs target the `develop` branch.