MAVMRF

Maritime Autonomous Vehicle Monitoring and Response Framework — a simulation-first Python pipeline for multi-sensor maritime detect, track, and classify.

Built by Fratres X AI — reviewable AI, autonomy, and defensive-technology prototypes with physics-first modeling and conservative maturity labels.

On a fresh clone, monitor mode uses simulation detections by default (no YOLO download). YOLO is opt-in via training, --pretrained, or --weights. There is no hosted web demo — clone it, run it, fork it.

Layout note: Application code lives in the marmf/ directory; the installable package name is mavmrf.

Still frame:

Contents

• Highlights
• Local demo (this is the live path)
• Quick start
• Detection modes
• Optional: train on synthetic data
• Architecture
• Design decisions and tradeoffs
• What we would change next
• Seeded benchmark
• Related work
• Related Fratres X threads
• Documentation
• Repository layout
• Tech stack
• Contributing
• Citation
• Disclaimer
• License

Highlights

• Multi-sensor simulation — sonar, acoustic, optical, and magnetic streams
• Honest detection modes — simulation default; YOLO when trained or explicitly requested
• Fusion & tracking — IoU-matched object IDs, weighted fusion, SORT-style tracks
• Operator outputs — bearing, estimated range, bearing rate, contact typing, change detection
• File replay — JSON frames via JsonFileSensorAdapter (incoming_data/samples/)
• Reproducible gates — seeded benchmark under docs/benchmarks/
• Automated tests + GitHub Actions CI

Local demo (this is the live path)

No cloud app. The demo is a local run that writes reports and visualizations under marmf/reports/.

This is the Fratres X open-source posture: you run the stack.

# Windows
cd marmf
scripts\demo.ps1

# Linux / macOS
cd marmf
chmod +x scripts/demo.sh
./scripts/demo.sh

Equivalent one-liner after install:

cd marmf
python main.py --mode monitor --no-trained --duration 10 --num-objects 8

Regenerate the README GIF from a short run:

cd marmf
python main.py --mode monitor --no-trained --duration 3 --num-objects 4
python scripts/make_demo_gif.py

Quick start

cd marmf
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
# source .venv/bin/activate

pip install -r requirements.txt
pip install -e .
python main.py --mode monitor --duration 10 --num-objects 8 --no-trained

From the repo root:

pip install -e marmf

Reports include detection_source (simulation, trained, pretrained, or explicit).

Detection modes

Mode	How to enable
simulation (default)	No flags; uses simulator optical detections
trained	After main.py --mode train; auto-loads best.pt
pretrained	--pretrained (downloads yolov8n.pt)
explicit	--weights PATH

Use --no-trained to skip auto-loading local trained weights.

Optional: train on synthetic data

cd marmf
python scripts/generate_dataset.py --clean
python main.py --mode train
python main.py --mode monitor

Architecture

See docs/ARCHITECTURE.md for pipeline diagram, module map, extension points, and how MAVMRF sits next to other Fratres X defensive-sensing / contested-autonomy work.

Simulated / file streams → preprocess → detect → track → fuse → report

Design decisions and tradeoffs

Maturity: simulation / prototype — not a fielded maritime C2 product.

Choice	Why	Tradeoff
Simulation detections by default	Fresh clone stays honest and offline; no silent COCO YOLO download	Optical “detections” are synthetic until you train or pass --weights / --pretrained
IoU match before fusion	Keeps sonar/acoustic/magnetic joins on the same contact when YOLO boxes differ from sim boxes	Assumes overlapping 2D boxes; not a full 3D association layer
SORT-style tracker	Fast, reviewable track continuity for demos and gates	No deep appearance re-ID; coasting behavior is deliberately simple
Weighted multi-sensor fusion	Makes the multi-modal story concrete in reports	Weights are heuristic, not learned calibration from real sensors
Clone-and-run only	Matches Fratres X “you run it, you own the stack” open-source posture	No hosted demo for drive-by clicks

This thread sits alongside Fratres X work on defensive sensing and contested autonomy: multi-modal streams, conservative fusion, and outputs you can audit — without claiming operational readiness.

What we would change next

• Real adapter implementations behind SensorAdapter (AIS / acoustic / optical feeds) with recorded replay fixtures
• Association beyond 2D IoU (bearing-range gates, timing uncertainty)
• Calibration / clutter models grounded in measured sensor noise, not only sim knobs
• Stronger track lifecycle metrics (continuity, ID switches) in the seeded benchmark
• Optional Docker one-liner for locked environments — still local, still yours

Seeded benchmark

Fixed-seed simulation gate (not field performance):

cd marmf
python scripts/benchmark.py --seed 42 --duration 5 --num-objects 6

Results live in docs/benchmarks/ (README.md + seeded_run.json).

Related work

MAVMRF is a simulation-first lab baseline. Domain surveys and open trackers that situate the design:

• Survey: Multi-sensor data fusion in maritime surveillance (PeerJ) — fusion methods; YOLO + tracking as common optical paths.
• Benchmark: Autoferry sensor fusion dataset — multi-sensor MOT fixtures with ground truth.
• Validated tracker: harbour-multi-sensor-tracking — radar/camera/AIS/GNSS + EKF/Hungarian, sim + harbour runs.

Full comparison table: docs/RELATED_WORK.md.

Related Fratres X threads

Sibling lab threads on fratres-x.com — same posture: physics-first modeling, conservative maturity labels, reviewable prototypes.

Thread	Focus
Charybdis	Contested autonomy — hybrid UUV navigation, conservative fusion, validation gates
Anti Edge Node	Defensive sensing — acoustic / RF / visual fusion, audit logs, field-node concept
HYPERLINK	Missile-defense modeling — imperfect model constellations, uncertainty, simulation

Profile pin checklist: docs/PROFILE_SETUP.md.

Documentation

Doc	Description
docs/README.md	Documentation index
docs/ARCHITECTURE.md	Pipeline and extension points
docs/RELATED_WORK.md	Surveys, benchmarks, how MAVMRF fits
docs/benchmarks/	Seeded reproducible gates
docs/ZENODO_SETUP.md	Mint a Zenodo DOI for releases
docs/SOLUTION_BRIEF.md	Executive narrative
docs/capability_matrix.md	Capability → evidence
docs/DEMO_SCRIPT_3_MIN.md	Demo script
CHANGELOG.md	Release history
SUPPORT.md	Where to get help
SECURITY.md	Vulnerability reporting

Full CLI reference: marmf/README.md.

Repository layout

Path	Description
marmf/	Core framework (package name mavmrf)
docs/	Architecture, brief, samples, screenshots, benchmarks
CONTRIBUTING.md	Setup, tests, CI
marmf/tests/	Pytest suite

Tech stack

Python 3.12 · OpenCV · NumPy · Ultralytics (YOLOv8) · PyTorch · Matplotlib · SciPy · pytest · ruff

Contributing

See CONTRIBUTING.md. By participating, you agree to the Code of Conduct.

Citation

See CITATION.cff. Prefer the “Cite this repository” button on GitHub when available.

Disclaimer

Portfolio prototype using simulated sensor data. Not intended for operational deployment without live sensor integration and validation. Built for scrutiny — not for inflated claims.

License

MIT — see LICENSE.