Memory-Based Navigation Research

A unified repository for outdoor memory-based navigation research on a small RC platform: synchronized video and GPS logging, HDF5 datasets with steering traces, and offline analysis to extract decision-point landmarks and organize imagery for downstream use.

The work evolved across several college-era folders; this repo is the canonical home for that narrative. Material from Autonomous Navigation (analysis and algorithm evolution) and GoPro (acquisition probes and camera-native GPS exports) is merged here with clear phase boundaries, documentation, and a triage area for weaker duplicates rather than silent deletion.

Problem

Experience-based navigation needs aligned perception and control segments. This project:

1. Acquires GoPro-class video over UDP with USB serial GPS (NMEA) and writes HDF5 groups with frame data and coarse geo attributes (src/capture_gopro_gps.py).
2. Exports frames for inspection (src/extract_hdf5_images.py).
3. Detects steering landmarks and sorts frames into labeled folders with Plotly diagnostics (src/mbn_steering_analysis.py).
4. Optionally runs heavier signal/ML experiments on the same HDF5 layout (experiments/combined_datasets_pipeline.py).

Phases of work (how the source folders map here)

Phase	Description	Where it lives
Acquisition	GoPro streaming, GPS alignment, HDF5 logging	src/capture_gopro_gps.py; sample GoPro GPS5 CSV tracks in data/gopro_gps_exports/ (from the college GoPro folder)
Core analysis	Landmark detection, false-positive handling, folder organization	src/mbn_steering_analysis.py (supersedes college MBNSteeringDataAnalysisAlg.py, kept under triage/)
Algorithm evolution	Early image readers and landmark sub-steps	archive/phase1-image-reader-evolution/
Extended experiments	Filtering, clustering, extra plotting (scipy/sklearn/statsmodels)	experiments/combined_datasets_pipeline.py
Utilities	Image-only export; re-open saved plots; read GPS CSV	experiments/extract_images_only.py, experiments/landmark_inspection.py, experiments/read_gopro_gps_csv.py

Narrative detail: docs/research-overview.md, docs/timeline.md, docs/repo-map.md.

Repository structure

├── src/                    # Primary capture + analysis scripts
├── experiments/            # Optional tools and heavier pipelines
├── data/gopro_gps_exports/ # Sample camera-native GPS CSV + README
├── archive/                # Historical algorithm scripts
├── docs/                   # Overview, timeline, methodology, repo map
└── triage/                 # Quarantined duplicates / uncertain artifacts

Tech stack

• Python 3.10+ recommended (repo uses from __future__ import annotations where noted)
• Core: NumPy, h5py, Pillow, Plotly, OpenCV, pyserial, pynmea2, goprocam
• Experiments (optional): pandas, matplotlib, scikit-learn, scipy, statsmodels — see requirements-experiments.txt

Setup

python -m venv .venv
.venv\Scripts\activate
# source .venv/bin/activate   # macOS / Linux

pip install -r requirements.txt
# Optional:
# pip install -r requirements-experiments.txt

Hardware for capture: GoPro in webcam/UDP mode and a USB GPS emitting NMEA. Serial port names are OS-specific (e.g. COM3 on Windows).

Usage

1. Live capture → HDF5

python src/capture_gopro_gps.py 0 100

• First argument: webcam device id/string for goprocam (same role as the original sys.argv[1]).
• Optional second argument: max frames (default 10).
• --show: OpenCV preview; quit with q.
• The process prompts for the GPS serial port; the GPS reader runs in a daemon thread so the program can exit after capture.

2. HDF5 → JPEG

python src/extract_hdf5_images.py path/to/capture.hdf5

Optional: -o myprefix for output filenames.

3. Steering / landmark analysis

python src/mbn_steering_analysis.py

Interactive prompts for folder vs file, windows, and optional manual edits. Outputs include organized image folders, plot.html / plot.json, and Analysis/landmarks.txt / steeringdata.txt next to the dataset.

4. GoPro GPS CSV (optional)

python experiments/read_gopro_gps_csv.py "data/gopro_gps_exports/GH010011_HERO9 Black-GPS5.csv"

5. Extended pipeline (optional)

python experiments/combined_datasets_pipeline.py

Requires requirements-experiments.txt.

Engineering / research notes

• Dataset assumptions: The main analysis expects camera datasets shaped (240, 320, 3) and steering datasets whose HDF5 paths contain steering — tied to the original logger layout.
• Interactivity: mbn_steering_analysis.py is driven by input(); batch automation would need refactoring.
• Capture robustness: UDP + goprocam behavior depends on firmware and network; error handling is minimal by design.
• Longitude sign: GPS parsing applies a western-hemisphere-style negation on longitude in capture_gopro_gps.py; adjust if your convention differs.

Validation

There is no automated test suite. Quick syntax check:

python -m py_compile src/capture_gopro_gps.py src/extract_hdf5_images.py src/mbn_steering_analysis.py

Limitations and future work

• No bundled HDF5 datasets; reproducibility requires your own logs.
• Extended experiment scripts are research-grade, not polished libraries.
• Triage holds superseded or incomplete college scripts; review before deleting — see triage/README.md.

License

This repository does not include a LICENSE file unless one is added by the maintainer. All rights are reserved until then.