BeachEye / SharkShield

This repo contains an experimental “hybrid” shark alert concept that combines:

1. Environmental risk derived from sea-surface temperature (SST) at a location (via Open-Meteo’s Marine API).
2. Vision detection (YOLOv8) that can confirm sharks in an uploaded image/webcam frame.

A Streamlit app (app.py) exposes (1) + (2) as an interactive UI.

---

How the hybrid concept works (high level)

Environmental step (SST → risk):

• Given a latitude/longitude, fetch today’s SST.
• Compare the SST to per-species SST ranges.
• Produce a risk score from 0–100%.

Vision step (YOLO confirmation):

• If the environmental risk is high enough, run YOLO on the camera/upload frame.
• If YOLO’s predicted class looks like “shark”, raise an alert.

The notebooks explore the research pipeline; the Streamlit app turns it into a user workflow.

---

Notebooks (what they do)

These .ipynb files are primarily exploratory / prototyping notebooks. They show multiple iterations of the same idea:

• Cleaning a shark-incident dataset.
• Computing a risk score from SST using species-specific SST temperature ranges.
• Enriching each incident with environmental variables (SST, air temp, wind, sometimes moon illumination).
• “Snapping” incident coordinates to a coastline for more reliable ocean/environment lookups.
• Visualizing enriched results (plots + a Folium map).
• Training/testing a YOLO model.

integration.ipynb

This notebook demonstrates the full hybrid pipeline at a code level (SST-based risk → conditional YOLO inference → alert message).

Key components:

1. Open-Meteo client + Moon illumination helper

• Uses openmeteo_requests with a retry-enabled session.
• Defines get_moon_illumination(date_obj):
  • Simple approximation using “days since a reference date” and a lunar cycle.
  • Returns an integer percentage illumination.

2. SST fetch from the Marine API

• Defines get_marine_weather_fixed(lat, lon, target_date):
  • Calls https://marine-api.open-meteo.com/v1/marine.
  • Requests hourly sea_surface_temperature.
  • Sets sst_c to the mean of returned SST values.
  • Returns a dict containing sst_c (and a schema for air_temp_c and wind_kmh, though the simplified function primarily computes SST).

3. Species SST preferences (simplified)

• Defines species_prefs with SST bands:
  • great_white: 12–24°C
  • tiger: 20–30°C
  • bull: 18–28°C

4. Environmental risk scoring

• Defines get_beach_risk(lat, lon, species_prefs):
  • Fetches today’s SST.
  • If SST is missing, returns None.
  • For each species band containing the current SST, adds 33 points.
  • Clamps to <= 100.

5. YOLO model loading

• Loads YOLO from the trained weights path:
  • /Users/kasmyabhatia/runs/detect/train/weights/last.pt

6. Hybrid alert function

• Defines hybrid_alert(lat, lon, frame_path):
  • Computes risk.
  • If risk is None or risk < 30, it skips vision.
  • Otherwise runs YOLO on frame_path.
  • Iterates YOLO detections and checks if the detected class name contains “shark” (case-insensitive).
  • Returns:
    • High alert if a shark is detected.
    • Otherwise a message indicating risk exceeded but vision did not find a shark.

---

vision.ipynb

This notebook focuses on the vision (YOLO) side of the hybrid system, including:

1. Setting up a YOLO dataset config

• Creates a YOLO data.yaml using yaml.dump(...).
• Config includes:
  • nc: 3
  • class names: ['Fish', 'Sharks', 'Turtles']
  • train and val both point into dataset/images in the snippet.

2. Training YOLO

• Uses YOLO("yolov8n.pt").
• Trains with model.train(data="data.yaml", epochs=50, imgsz=640, batch=16, device="cpu").

3. Inference and quick evaluation

• Loads the trained model from:
  • /Users/kasmyabhatia/runs/detect/train/weights/last.pt
• Chooses a test image:
  • Prefer first image from dataset/images/val.
  • Else downloads a sample beach image (sample_beach.jpg).
• Runs detection via results = model(test_image_path) and visualizes using results[0].show().
• Prints detected class names and confidences.

4. Vision + environmental risk “simulation”

• Demonstrates how YOLO would be conditionally run based on environmental risk:
  • Uses a Bondi coordinate (example: lat=-33.8915, lon=151.2767).
  • Attempts to call get_beach_risk(...).
  • If risk > 30, runs YOLO on the same test image.
  • Checks detections for class names containing “shark”.

5. Extra YOLO test cells

• Example direct inference:
  • results = model("shark.jpg")
  • results[0].show()

6. Dataset folder scaffolding for YOLO

• Shows creation of a YOLO-style dataset directory under overfishing_dataset/.
• Writes an overfishing_dataset/data.yaml.

7. Stub for a different predictor

• Imports predict_on_images from src.marine_detect.predict and calls it with placeholder paths.
• This referenced src/... module does not appear to be included in the repo snapshot visible here.

---

new.ipynb

This notebook demonstrates the data-engineering + environment enrichment side of the project:

1. Load and clean shark incident data

• Loads geocoded-global-shark-attacks.csv.
• Keeps rows with valid latitude/longitude and a valid incident date.
• Renames coordinates into:
  • latitude
  • longitude
• Keeps columns like fatal_y_n if present.

2. Define species SST bands + SST→risk function

• Defines species_prefs with SST ranges.
• Defines risk_from_sst(sst) returning a 0–100% score.

3. Open-Meteo API utilities with caching

• Uses Open-Meteo Marine API for SST and Open-Meteo Archive API for air temp & wind.
• Defines get_moon_illumination(date_obj).
• Defines get_marine_weather(lat, lon, target_date) combining:
  • SST (marine endpoint)
  • air temp and wind (archive endpoint)
• Defines get_cached_or_fetch(lat, lon, target_date):
  • Uses a local weather_cache.csv keyed by (lat, lon, date).

4. Fetch risk for today

• Defines get_beach_risk(lat, lon):
  • Fetches cached or live SST.
  • Returns the risk derived from SST.

5. Download coastline + snap incidents to ocean/coast

• Downloads Natural Earth coastline zip (ne_110m_coastline.zip).
• Loads it with geopandas.
• Defines snap_to_coast(lat, lon, max_dist_km=100) which:
  • Finds nearest point on the coastline geometry.
  • Rejects points farther than the threshold.
• Creates df_snapped with snapped_lat/snapped_lon.

6. Enrich snapped incidents with environmental variables

• Creates columns:
  • sst_c, air_temp_c, wind_kmh, moon_pct
• Loops over all snapped incidents:
  • Computes moon illumination for incident_date.
  • Fetches environmental variables via cached API calls.
• Writes enriched_attacks_final.csv.

7. Visualizations

• SST histogram.
• Monthly incident bar chart.

8. Real-time risk for sample beaches + Folium map

• Computes and plots risk for a list of example beaches.
• Creates a Folium map (shark_risk_map.html) using:
  • snapped_lat/snapped_lon
  • a categorization function sst_to_risk_cat into {Low, Medium, High, Unknown}.

9. Extra experiments

• The notebook contains additional cells exploring SST datasets via xarray and referencing an sst.mnmean.v4.nc file.

---

Dataset / output files referenced

From the repo root and notebooks, the following outputs/inputs are used:

• geocoded-global-shark-attacks.csv (input dataset)
• enriched_attacks_final.csv
• enriched_attacks_snapped.csv
• enriched_attacks_snapped_100km.csv
• weather_cache.csv (temporary cache while enriching)
• shark_risk_map.html (Folium output)

---

Streamlit app (app.py)

app.py is the executable UI version of the idea:

• Environmental risk panel

  • Inputs: latitude/longitude
  • Uses SST risk calculation.
  • Displays a metric and risk tier messages.

• Vision detection panel

  • Accepts image upload or webcam capture.
  • Runs YOLO and shows annotated results.
  • Alerts if a detected class name contains “shark”.

• Hybrid simulation button

  • Runs risk first.
  • If risk is high enough and an image frame exists, it runs vision and only escalates if both agree.

---

Limitations / assumptions baked into the notebooks

1. SST API coverage: the marine SST endpoint may not return SST for points in coastal bays / near-land areas (masking).
2. Coordinate snapping approximation: snapping uses geometric distance to a coarse coastline dataset; it assumes “nearest coastline” is a good proxy for ocean grid sampling.
3. YOLO class-name matching: the code checks whether the YOLO model.names[cls] contains the substring “shark”—so correct labeling/naming is critical.
4. Risk model simplicity: risk is purely derived from whether today’s SST falls into predefined species SST bands.

---

How to run the app

1. Install dependencies (example):
   • pip install streamlit ultralytics openmeteo-requests retry-requests pillow
2. Run:
   • streamlit run app.py
3. Use the UI to input a beach location and upload/capture an image.

---

Notes about the repository structure

Many files under shark_files/ appear to be static assets used by generated HTML/pages (e.g., maps). The core logic for risk + vision lives in:

• app.py
• the notebooks: integration.ipynb, vision.ipynb, new.ipynb