resolve_place
Resolve place name
Turn a place name ('outside Halifax', 'Strait of Hormuz', 'Bergen,
Norway') into water coordinates. Maritime gazetteer first (ports resolve
to their approaches, straits/seas to a representative point), then
OpenStreetMap. Points on land or shallower than min_depth_m are walked
seaward along the gazetteer bearing (or the nearest direction) until deep
enough; the original point and the snap are reported. offshore_km pushes
the point further out along seaward_bearing_deg. All location tools also
accept `place` directly, so a separate call is only needed to inspect.
Parametersplacerequiredmin_depth_moffshore_kmseaward_bearing_deg
Seafloor depth from Clairwave-served global bathymetry (~450 m resolution). Location:
lat/lon or `place` (name resolved to a water point, echoed in `location`).
Without a bearing: depth at the point. With a bearing (compass degrees,
0 = north): a depth profile along that transect out to range_km.
Parameterslatlonplacen_pointsrange_kmbearing_deg
get_sound_speed_profile
Sound speed profile
Seasonal sound-speed profile c(z) at a location (lat/lon or `place`
name, e.g. "Halifax approaches") for a calendar month
(1-12), from Clairwave-served seasonal temperature/salinity climatology, plus the seabed
parameters (compressional/shear speed, density ratio, attenuation,
sediment type) at the same point. Cached per 0.1 degree.
Parameterslatlonmonthrequiredplace
run_transmission_loss
Transmission loss (RAM PE)
Run a physically grounded transmission-loss simulation (RAM parabolic
equation) from a source at (lat, lon or `place`, depth) along a compass bearing.
Bathymetry, the seasonal sound-speed profile (`month`) and
seabed parameters are fetched for the location automatically. Returns TL
vs range at the receiver depths (default: source depth, 10 m, 100 m,
mid-water), grid statistics, and the full replication bundle. Show
`open_url` to the user as a clickable link.
Parameterslatlonmonthplacerange_kmbearing_degrequiredfrequency_hzrequiredsource_depth_mrequiredreceiver_depths_m
estimate_detection_range
Detection range (sonar equation, passive or active)
Sonar detection range along a bearing from a location (lat/lon or `place`).
Transmission loss (TL) is ALWAYS computed: RAM parabolic equation with the
location's bathymetry, seasonal sound speed (`month`, default: current month)
and seabed. Every other sonar-equation term is optional — anything not given
gets a stated, typical default listed in `assumptions` with its source.
Tell the user which values were assumed.
Detection threshold DT is derived from processing gain (unless given):
detection index d from `pd`/`pfa` (default 0.5 / 1e-4 → d ≈ 13.8), then
passive (incoherent energy detector): DT = 5·log10(d / (B·T)),
B = analysis band, T = `integration_time_s` (default 1 s);
active (matched filter): DT = 10·log10(d / (2·B·τ)),
B = `bandwidth_hz` (default 100 Hz LFM), τ = `pulse_length_s` (default 0.5 s).
DT is in-band SNR, so it can be negative — that IS the processing gain.
mode="passive": SE = SL − TL − (NL − DI) − DT. Default target = merchant ship
(bulk carrier, AIS 70, 200 m @ 12 kn, JOMOPANS-ECHO decidecade band level) at
6 m; receiver ½ water depth (≤ 30 m), omni (DI 0 — give directivity_index_db
for an array). `frequency_hz` is optional: the tool always also evaluates
the target's MOST DETECTABLE 1/3-octave band in 50–2000 Hz (`best_band`) —
ships are loudest there; a user frequency is reported as asked. If you give
`source_level_db` without `frequency_hz`, the range is evaluated at 50 Hz.
mode="active" (monostatic, `frequency_hz` required): SE = SL − 2·TL + TS −
(NL − DI) − DT, TL from the sonar to the target depth. Defaults: hull sonar
at 7 m, SL 220 dB, TS 10 dB (large underwater object, beam aspect), target ½ water
depth (≤ 50 m), DI 20 dB (hull array). Noise-limited only: reverberation is
NOT included (often the limit in shallow water).
NL (unless given) = Wenz ambient noise at the CURRENT forecast wind at the point
(
Parameterspdlatlonpfamodemonthplacebearing_degbandwidth_hzfrequency_hzmax_range_kmnoise_level_db+9 more
run_bellhop_volume
Bellhop 3D TL volume (stored run)
Full 3D transmission-loss volume around a source (lat/lon or `place`)
with Bellhop (all bearings), stored on the platform under a run id. Show
`open_url` to the user as a clickable link: it opens this run visualized. Returns the run id,
the replication metadata (SSP, seabed, bounding box) and file links
(uint8 TL cube .npy + JSON sidecar). Any frequency and radius (keep radius
<= ~50 km for reasonable run times).
Parameterslatlonmonthplaceradius_kmfrequency_hzsource_depth_m
search_vessels
Search vessels (AIS)
Search live AIS vessels by name or MMSI prefix (global feed).
Parameterslimitqueryrequired
vessels_near
Vessels near a point (AIS)
Live AIS vessels within radius_km of a point (lat/lon or `place`), nearest first, with
position, course/speed, type, dimensions and last-update time.
Parameterslatlonlimitplaceradius_km
get_vessel
Vessel details + 3D model
Everything about one vessel: live AIS position/track and static
particulars, plus its 3D model (unique photo-derived model if generated,
else the class archetype) with GLB URL (bow=+Z, up=+Y) and platform links.
Parametersmmsirequired
vessel_source_level
Vessel source level
Underwater radiated-noise source level of a ship (monopole, dB re 1 uPa m, 6 m
reference source depth): decidecade spectrum (10 Hz - 100 kHz; model bands to
31.5 kHz, validated 20 Hz - 20 kHz) and broadband level, from the JOMOPANS-ECHO
reference spectrum model (MacGillivray & de Jong 2021, J. Mar. Sci. Eng. 9:369),
fitted to 1862 measured ship passes. Individual ships scatter about +/-6 dB rms per band.
Give an MMSI (live AIS type/speed/length are used) or explicit AIS ship_type / speed /
length. vessel_class overrides the AIS mapping (e.g. "vehicle_carrier", which has no
AIS type). Missing speed = the class reference speed; missing length = the class
mean length of the measured ships. The spectrum is usable directly as `sl_spectrum`.
Parametersmmsibeam_mdraft_mlength_mspeed_knship_typevessel_class
get_vessel_photo
Vessel photo
Photograph of a vessel from Wikimedia Commons, with attribution.
Parametersimommsiname
habitat_received_level
Habitat received level (vessel noise)
Broadband received level (dB re 1 uPa) at a fixed site — a fish farm,
reef, hydrophone or marine protected area — from the ships around it,
power-summed. Each vessel's source level comes from its AIS class, speed
and size; transmission loss is a fast broadband model, so this is a
screening estimate (use run_transmission_loss for exact site physics).
hours_back = 0 uses the live snapshot; > 0 reconstructs a time series from
the AIS archive in 10-minute bins (max/median/quiet levels). Location:
lat/lon or `place`. Show `open_url` to the user as a clickable link.
Parameterslatlontopplacehours_backmax_range_km
What Clairwave provides, which models/data back each tool, and limits.
Takes no parameters.