DroneRadar — proposed propagation and observation contract
Versioned conceptual interface with units, null behavior and a separate detector-calibration layer.
Status and purpose
Proposed conceptual contract coverage-contract/0.1; no API or schema implementation is claimed. It separates reusable propagation predictions from sensor observations and empirically calibrated detection estimates. Existing app and ML outputs use different assumptions; an adapter must explicitly translate them instead of inheriting defaults.12
Propagation request
| Field group | Required contents and conventions | Missing/invalid behavior |
|---|---|---|
| Identity/version | request ID, scene ID, model ID/version/hash, config hash, timestamp UTC | Reject missing model/config provenance |
| Geometry | Geographic bounding polygon WGS84 lon/lat, explicit projected CRS identifier and metric raster affine transform, width/height, resolution metres, axis order and cell-center convention | Reject ambiguous CRS, units or dimensions; no silent lat/lon swap |
| Surface/structures | Terrain source/version/date; elevation vertical datum; buildings/heights/material assumptions, mask and NoData coverage | NoData remains unknown, not zero-height or free space; missing buildings must be disclosed |
| Terminals | Tx/Rx coordinates, each height in metres with reference AGL or named absolute vertical datum; receiver height layers; fixed terminal versus swept terminal role |
Reject unexplained altitude references; convert only with compatible terrain/datum |
| Signal | center frequency Hz, channel bandwidth Hz if power/noise used, signal class or explicit unknown | Unsupported frequency/domain flagged; unknown signal class allowed for path-gain-only request |
| Antennas/power | Tx conducted power dBm, Tx/Rx gains dBi and orientation/pattern, polarization, feeder/mismatch losses dB; or explicitly declared EIRP dBm | Path gain may be returned without power. Received power/link margin require sufficient assumptions. Do not count Tx gain twice when EIRP supplied |
| Evaluation controls | Prediction quantity, floor/censoring convention, requested support mask, domain policy | Reject unsupported quantity or return a labeled unsupported result |
For receiver-placement planning, the fixed terminal is the candidate detector and the swept terminal is the emitter at each height/cell. A controller-centered map cannot simply be relabeled as a detector map. Any use of reciprocal propagation must preserve corresponding frequency, geometry, antenna patterns and model assumptions; it does not transfer receiver decoding/classification performance.
Propagation result
Return metadata plus raster/vector layers. Every layer carries quantity, unit, sign convention, height layer, model/domain and NoData mask.
path_gain_db: non-antenna channel gain under stated model convention; negative attenuation. If a chosen model includes antenna or equipment factors, adapter must strip or explicitly declare them; otherwise this field is unavailable.path_loss_db: positive loss, equal to-path_gain_dbonly under the same declared convention.received_power_dbm: optional link-budget calculation with complete power/gain/loss assumptions.link_margin_db: optional received power minus a declared threshold. Threshold is receiver/signal/bandwidth dependent; it is not universally the ML training floor. Preserve exact floor values: the RadioMapSeer loader floor is −127.168 dB, while historical prose often rounds it to −127.2. Thresholding a clipped value at a lower rounded threshold can turn censored pixels into apparent coverage. Use uncensored values where available or return unknown/bounds.support_mask: tested domain, extrapolated, missing scene, building/interior excluded, censored, invalid. Keep below-floor censoring separate from missing data and from no simulated ray.uncertainty: method and provenance, or explicitnot-calibrated. Seed spread and scenario disagreement may be included as sensitivity diagnostics; neither is automatically a calibrated confidence interval.warnings/provenance: units/conversions, approximation/domain warnings, underlying reference model/data hashes, generation code commit, runtime/hardware and calibration evidence ID.
Proposed bookkeeping equation, with path gain excluding antenna/equipment effects:
received_power_dbm = tx_conducted_dbm + tx_gain_dbi + rx_gain_dbi + path_gain_db - equipment_losses_db
With EIRP, replace conducted power plus Tx gain by EIRP and state which Tx-side losses it already includes. This equation defines interface accounting; it does not certify the propagation model. Do not derive an SNR/SINR without compatible receiver bandwidth, noise/interference and calibration information. Dataset gray values, dB path gain and dBm power are different quantities.12
Detector observation record
Propose a distinct event stream, adapted only after actual partner sample records and rights are available:
| Group | Proposed fields |
|---|---|
| Sensor/config | pseudonymous sensor ID, hardware/firmware and calibration version, site/config effective interval, antenna and scan configuration |
| Time/exposure | observation UTC, sensor ingestion UTC, clock accuracy, active/dwell interval, channel/frequency, uptime/health and known outages |
| Measurement | observation kind (RID packet, RF alert, track, etc.), RSSI dBm only if supported/calibrated, noise/SNR with stated units, confidence with documented meaning |
| Position | receiver position/height and uncertainty; emitter position/height and provenance (broadcast, estimated, ground_truth) separately |
| Identity/quality | source event ID, signal/protocol identifier if available, deduplication lineage, validation status and original schema version |
| Rights | collection/use/retention/redistribution policy reference; restrict identifiers and locations to the actual entitlement |
All unavailable measurement fields are null with a reason. An RF classifier score need not be a probability; a Remote ID location may be broadcast data; a radar track is a distinct measurement. These distinctions follow the existing landscape evidence.3
A non-detection requires a separate exposure/ground-truth record: known target presence or known transmission, receiver active at relevant channel/time, scenario conditions and evaluation window. A missing event alone is unknown. Aggregate flight/controller signal bars do not supply this exposure contract.1
Detection estimate — later evidence gate
Only after calibration, expose a clearly conditioned estimate such as P(valid observation of class C within window T | emitter active, scene, receiver configuration, operating conditions). Define success (reception, valid packet, alert or track) and false-alarm unit before fitting. Return model/calibration dataset provenance, domain/support, confidence method and evaluation sample size. If calibration is absent, detection_probability=null, reason no-detector-calibration.
Network estimates require joint/empirical validation. A union formula based on multiplying receiver miss probabilities assumes independence; common terrain, interference, protocol support and uptime may correlate misses. Do not silently use it as validated network coverage.
Proposed contract acceptance checks
Test signs/units and EIRP bookkeeping; CRS/axis/cell transforms; AGL/absolute conversion; floor versus NoData handling; rejected unsupported frequency/height; model/config hashes; null probability without calibration. Compare exported fixture values with standalone model outputs. Confirm actual detector schema/time semantics before adapter implementation. These are proposed later checks, not executed tests.
-
Existing baseline uses link budgets while ML uses simulator path-gain scaling; main finding sources include service, propagation and data code. ↩↩↩
-
SpectrumNet inferred encoding/censoring and coarse-grid transfer illustrate adapter/domain risks. ↩↩
-
Existing synthesis, technical background and canonical profile source chains distinguish observation types and data entitlements; reused read-only. ↩