Technical documentation

How to use OCEASTRA services, API formats and deployment notes.

Getting access

All interactive services (Noise Estimation, Airgun Estimation, Vessel Trajectory) require a registered account. Create an account with email/password or sign in with Google, GitHub or Microsoft when configured by your administrator.

Noise Estimation (web UI)

After signing in, open Noise Estimation. The full MNAT interface provides:

• Sea area — select a predefined sea region and use live AIS vessels
• Custom box — draw or enter lat/lon bounds
• API — browse and load a JSON snapshot (one timestamp, multiple vessels)

Click Start Process to run Bellhop transmission-loss estimation (if no model exists), train the ML model, and predict per-vessel noise. Use depth controls and the heatmap layer; download the combined JSON when complete.

Vessel Trajectory (web UI)

After signing in, open Vessel Trajectory. Choose a sea, custom box or API JSON area (same modes as Noise Estimation). Vessels inside the selected + extended area are shown with heading arrows (same style as Noise Estimation). Thin track lines accumulate in the browser from live AIS updates onward — no database history is loaded.

JSON request format (API mode)

{
  "request_id": "snapshot-001",
  "timestamp": "2026-06-28T08:00:00Z",
  "area_box": {
    "min_lat": 45.0, "max_lat": 45.2,
    "min_lon": 12.7, "max_lon": 12.95
  },
  "processing": {
    "frequency_hz": 100,
    "depth_min_m": 0, "depth_max_m": 50,
    "depth_step_m": 5,
    "grid_spacing_deg": 0.1,
    "propagation_model": "bellhop"
  },
  "vessels": [
    {
      "user_id": 247341800,
      "ship_type": 70,
      "dimension_a": 100, "dimension_b": 20,
      "dimension_c": 10, "dimension_d": 8,
      "max_static_draught": 6.1,
      "name": "VESSEL_ONE",
      "latitude": 45.10, "longitude": 12.80,
      "sog": 12.0, "cog": 45.0
    }
  ]
}

Batch REST API

Programmatic jobs (same payload) are available at:

• POST /api/jobs — submit JSON body
• GET /api/jobs/{id} — poll status
• GET /api/jobs/{id}/result — download heatmap JSON

OpenAPI reference: /docs (Swagger UI — auto-generated).

Result format

Exported files contain { "data": [ { "Latitude", "Longitude", "Depth", "Value" }, ... ] } where Value is received noise level in dB re 1 µPa.

Propagation stack

• Bellhop (Acoustics Toolbox) for ray-based transmission loss
• GEBCO bathymetry and WOA sound-speed profiles
• Stacking regressor (RF + GB + meta) per area/frequency/grid
• Vessel source levels from AIS dimensions, type and speed

Method accuracy (ML vs Bellhop)

On the Noise Estimation page, scroll below the map to Method accuracy (ML vs Bellhop) (or use the Method accuracy ↓ hint). Click Evaluate after a model exists for the current sea/harbor, frequency and depth settings (run Start Process until the SR model is trained). The panel reports how closely the proposed ML field matches independent Bellhop physics at the same receivers.

What is compared

• Truth (pure Bellhop) — for each selected ship and each random receiver, run a fresh Bellhop transmission-loss calculation along the ship→receiver track (GEBCO bathymetry + sound-speed profile). Received level is RL = SL − TL (dB re 1 µPa). Levels from all ships are converted to linear intensity, summed, then converted back to dB (incoherent sum).
• Proposed (ML) — the saved StackingRegressor predicts received level for the same ship→receiver pairs (distance, bearing, depth and related features), then sums ships the same way.

This is not a comparison against interpolated training-PKL grids. Evaluate uses live Bellhop runs at the sample points so the check is independent of the training field.

How samples are chosen

• Receivers — by default 20 points inside the wet area: about 40% in a near-ship annulus (~0.15–0.8 km from an eval vessel) and the rest area-wide. That mix avoids scoring only far-basin receivers.
• Ships — up to 3 vessels from the Bellhop training PKL, chosen with a spatial diversity rule (farthest-point / maximin): seed with the newest ship, then add ships that maximize distance to those already selected (near-duplicates within ~0.5 km are collapsed). Source level and source depth come from AIS / vessel metadata when available.
• Depth — evaluation uses the active visualization depth layer(s); metrics are reported for the configured layer set (often a single layer in harbor mode).

Why Bellhop sample levels often look “low” (~60–70 dB)

Harbor ship source levels at 8 kHz are typically ~115–125 dB. The map hotspot next to a vessel is ≈ SL. At mid-range, geometric spreading alone gives RL ≈ SL − 20·log10(r): about 64 dB at 0.5 km and 58 dB at 1 km for SL ≈ 118 dB. Evaluate’s Bellhop values in the 60–70 dB band at those distances are therefore expected — they are not a broken estimator. Compare them to the geometric reference shown in sample tooltips, not to the near-ship map peak.

Metrics and map

At each receiver the error is Δ = RLML − RLBellhop (dB). The panel shows:

• MAE / RMSE — mean absolute and root-mean-square error over receivers
• Bias — mean signed error (positive ⇒ ML louder than Bellhop on average)
• Pearson r / R² — linear agreement between ML and Bellhop totals
• Within 5 dB — share of receivers with |Δ| ≤ 5 dB

The right-hand map colours each sample by |Δ| so you can see where the methods diverge (e.g. near piers, channel bends or sparse training coverage).

Interpreting results

• Good (open sea, well-trained) — MAE/RMSE of a few dB, Pearson r ≫ 0, a large share within 5 dB.
• Bias ≈ MAE (same sign) — systematic offset (ML consistently louder or quieter than Bellhop), not just random scatter.
• Negative Pearson r / strongly negative R² — the spatial pattern disagrees (hot/cold spots swapped or washed out), not something a constant offset can fix.
• Harbor / pier areas — Evaluate and the live map both use the StackingRegressor with water-path features (Option B). Retrain after enabling harbor masks so the model learns occlusion; scores then match what you see on the map (no separate display physics field).

If scores are poor — what to do

1. Confirm frequency, depth and area match the model you trained (Apply Parameters, then process until the SR model exists).
2. Train more Bellhop vessels in that area (more coverage → better ML). Re-run Evaluate after several new ships merge into the PKL.
3. In harbors, treat Evaluate as a check on geometric ML. Improving pier/channel fidelity needs harbor water masks and water-path physics (see harbor acoustic accuracy notes), not only more open-water radials.
4. Compare the |Δ| map: clusters of large error near piers or behind land point to occlusion / land-bleed, not a global SL bug.
5. Do not expect Within 5 dB ≈ 100% until the training set densely covers the basin and land barriers are handled in the acoustic path.

When to run it

• After Apply Parameters and at least one successful process that produced an SR model + training PKL for that configuration.
• Optionally after each model update (the engine can schedule the same check automatically).
• Prefer stopping a heavy in-progress Bellhop training job before Evaluate if you want the fastest run; evaluation still runs serially for stability.

Defaults (n_points, max_vessels, real-Bellhop mode) live under TU_interface.method_evaluation in the engine config.json.

Support

Contact [email protected] for enterprise deployment, OAuth setup and SLA options.