Table of Contents

1 · What is Airplane Scatter?

Airplane Scatter (also known as Aircraft Scatter) is a radio propagation phenomenon in which a passing aircraft reflects or scatters FM radio signals between a transmitter and a receiver that would otherwise not be in direct line of sight of each other. The effect is real and well documented in the DX community.

When a large commercial aircraft — typically at cruise altitude between 8,000 m and 12,000 m — passes near the geometric midpoint of the great-circle path between a transmitting antenna and a receiving antenna, it can act as a mirror. The signal is scattered off the fuselage, wings, and engines and redirected toward the receiver. The scatter event is short-lived (typically 10–60 seconds) but can produce signals strong enough to decode RDS data or hear audio from a distant station.

Key factors that determine whether a scatter event will be detectable:

• Aircraft altitude: Higher cruise altitudes increase the radio horizon and improve reflection geometry.
• Aircraft size: Larger airframes (wide-body jets) present a greater radar cross-section and scatter more energy.
• Transmitter ERP: Higher effective radiated power means more energy available to scatter.
• TX–RX distance: Airplane scatter works best over paths of 400–1500 km where both TX and RX are below each other's radio horizon.
• Reflection angle: The angle at which the signal hits the aircraft fuselage relative to both antennas strongly affects efficiency.
• Fuselage alignment: If the aircraft's longitudinal axis is roughly perpendicular to the bisector of the TX–AC–RX angle, reflection is more efficient.
• TX antenna beam direction: Directional transmitter antennas illuminate only a limited arc. Scatter is only possible if both the aircraft and the receiver direction fall within this arc.

2 · Why a Plugin?

Without prediction tools, a DX operator has no way of knowing in advance that a scatter opportunity is about to occur. The window is narrow — typically under one minute — and the aircraft moves continuously. By the time a DX signal is noticed and identified, the aircraft may have already moved away from the optimal reflection geometry.

3 · Architecture – Data Sources and Components

4 · Simple Explanation – How the Plugin Works

Imagine you are trying to shine a laser pointer at a mirror to hit a distant target. If the mirror (the aircraft) is positioned at exactly the right angle between the laser source (the transmitter) and the target (your receiver), the beam bounces directly to you. The plugin computes this geometry for every aircraft currently in the sky, for every known FM transmitter in a 750 km radius, and tells you which combinations are close to the ideal reflection angle — before they occur.

4.1 · The Reflection Geometry

For a scatter event to occur, three points must be approximately collinear in a specific angular relationship: the transmitter, the aircraft, and the receiver. The aircraft should be positioned roughly on the great-circle path between transmitter and receiver, at a point where the angle of incidence (TX→AC) approximately equals the angle of reflection (AC→RX).

The plugin computes the great-circle intersection point — the point on the TX–RX path closest to the aircraft's current track — and evaluates the reflection quality based on cross-track distance, reflection angle, aircraft altitude, transmitter ERP, and aircraft fuselage alignment. The transmitter's beam direction (if known from the userlist) is also factored in as a hard gate. Finally, a two-pass topography check ensures the aircraft isn't physically blocked by mountains. The result is a single scatter score from 0–100%.

4.2 · Score – What does the Percentage Mean?

The scatter score is a weighted composite of physical factors. The score is designed so that aircraft flying in the Sweet Spot — just barely above both the TX and RX horizon envelopes with the flattest possible elevation angle — receive the highest scores. This directly reflects the physical reality of airplane scatter: the most efficient scatter occurs when the signal grazes the aircraft at the lowest possible elevation angle from both ends simultaneously.

The raw score is then multiplied by an aircraft size multiplier based on the ADS-B category code, and additionally by the beam multiplier from the TX antenna beam direction:

Hard rejection gates (score = 0, aircraft not shown)

• Aircraft more than 500 m below either horizon envelope. A 500-meter diffraction tolerance is allowed to account for knife-edge diffraction over mountains, though aircraft in this "shadow zone" receive a score penalty.
• Elevation angle from TX or RX exceeds 9°
• TX–RX path distance shorter than minTxRxDistKm (default 400 km)
• Aircraft outside the dynamic ellipse defined by TX and RX positions
• Aircraft speed below 50 kts or altitude below 1000 ft
• Aircraft or RX direction falls outside the TX antenna beam arc (requires userlist1.csv)

Score colour scale in the UI

4.3 · ETA – The Countdown Timer

The ETA (Estimated Time of Arrival at the crossing point) is displayed as a countdown timer in the format −M:SS (approaching) or +M:SS (receding). When the aircraft is within 5 seconds of the optimal crossing point, the display switches to NOW ✓ in green.

4.4 · Transmitter Database (fmdx.org)

The TX database originates from maps.fmdx.org/api/ and contains all known FM transmitters worldwide. This database is loaded and managed entirely on the server side by airplanescatter_server.js. Only the pre-filtered result (typically under 200 KB) is sent to the browser, instead of the full 50 MB raw file.

Each transmitter entry provides:

• Frequency (87.5–108.0 MHz)
• ERP – Effective Radiated Power in kW
• Location – latitude, longitude, city name, ITU country code
• Station name / PS name – programme name from fmdx.org
• Polarisation – H (horizontal), V (vertical), or mixed

Supplementary data (beam direction, RDS PI code, PS name, programme name, language) can optionally be loaded from the userlist1.csv file obtained from fmscan.org (see §5.18 and §7.2).

4.5 · Aircraft Data (ADS-B)

Live aircraft positions are fetched every 15 seconds from ADS-B REST APIs. The plugin simultaneously queries five public API endpoints in parallel to ensure maximum coverage and automatic error handling (see §5.10). Each aircraft record provides:

• ICAO 24-bit address – unique aircraft identifier
• Callsign / Registration
• Latitude / Longitude – current position
• Barometric altitude in feet
• Ground speed in knots
• Track – heading over ground in degrees
• Vertical speed in ft/min
• Category code – ADS-B emitter category (A1–A7, B1–B6, C1–C3)

Aircraft on the ground (alt_baro = "ground") or with a speed below 50 knots or an altitude below 1000 ft are silently excluded from all scatter calculations.

4.6 · Elevation Profile

When a transmitter is selected from the list or map, the plugin renders an interactive terrain elevation profile along the great-circle path from the receiver to the transmitter. The profile shows:

• The terrain surface (blue filled, from opentopodata.org SRTM 90 m data)
• The receiver line-of-sight ceiling (red line) – the minimum height an obstacle must be below for the TX not to be in direct LOS from the RX
• The transmitter line-of-sight ceiling (yellow line) – the same from the TX side
• The scatter zone (purple shaded) – altitudes at which an aircraft must fly to be geometrically above both LOS ceilings simultaneously
• The Sweet Spot corridor (green shaded band) – the ideal altitude window for maximum scatter efficiency, explained in detail in §4.7
• The aircraft positions (coloured dots) with callsign and altitude labels
• Dashed lines from TX and RX to each aircraft showing the signal path

The profile is fully interactive: mouse-wheel to zoom horizontally, click-drag to pan, a vertical slider to scale the altitude axis, and a hover tooltip that displays terrain height, elevation angles from both ends, and aircraft elevation angles at the cursor position.

4.7 · The Sweet Spot – Ideal Scatter Corridor

The Sweet Spot is displayed as a semi-transparent green band in the elevation profile. This is the single most important visual indicator for understanding whether a scatter event is likely to be strong and audible.

What is the Sweet Spot?

For airplane scatter to work optimally, the aircraft must simultaneously satisfy two angular constraints — one seen from the receiver side and one seen from the transmitter side:

• From the RX side: The aircraft must be at a low elevation angle — no more than approximately 5° above the receiver's horizon.
• From the TX side: The aircraft must be very close to the transmitter's radio horizon — ideally no more than approximately 1° above it.

The Sweet Spot is the altitude band along the TX–RX path where both conditions are satisfied at the same time. An aircraft flying through this green corridor is in the ideal geometric position to produce a strong, detectable scatter signal.

How to use the Sweet Spot in practice

• If the aircraft dot falls inside the green Sweet Spot band → optimal scatter is occurring or imminent. Tune to that frequency and listen carefully.
• If the aircraft dot is in the purple zone but outside the green band → scatter may still occur but geometry is suboptimal.
• If the aircraft dot is below the purple zone → no scatter is possible, unless it lies within the 500m diffraction tolerance.
• If the Sweet Spot band is very narrow or absent → the path geometry is not favourable for airplane scatter regardless of aircraft altitude.

4.8 · The Map Panel – Display Elements

5 · Technical Deep Dive

5.1 · Scatter Score Calculation

The core scoring function calcScatter(ac, rxLat, rxLon, rxElevM, tx) is called for every (aircraft, transmitter) pair that passes the spatial pre-filter. It performs three steps: compute the ETA to the crossing point, evaluate the score at a series of forecast positions, and return the best score found.

Step 1 – Crossing point and ETA

const crossPt = gcIntersectionPoint(txLat,txLon,rxLat,rxLon,ac.lat,ac.lon,ac.track);
const speedKmS = (ac.speed * 1.852) / 3600;
const distToCross = haversineKm(ac.lat,ac.lon,crossPt.lat,crossPt.lon);
let etaSec = distToCross / speedKmS;
// Negate if aircraft is flying away from crossing point
const brgToCross = bearingDeg(ac.lat,ac.lon,crossPt.lat,crossPt.lon);
if (Math.abs(normalizeAngle180(ac.track - brgToCross)) > 90) etaSec = -etaSec;

Step 2 – Forecast evaluation

The aircraft position is dead-reckoned to 5 forecast time steps: 0, 60, 120, 180, 300 seconds. For each step the inner evaluation function _evalScatterAt() is called and the best score is retained. An early-exit stops the loop as soon as a score of 95 or higher is found.

Step 3 – Inner evaluation: beam gate, diffraction tolerance, and terrain-aware horizon check

Before any score is computed, two hard gates are applied in sequence. First, the beam gate: if userlist data is available for this TX, the bearing to the aircraft and the bearing to the RX are both checked against the antenna beam arc. If either lies outside the beam, the candidate is rejected immediately without computing the terrain envelope. Second, the terrain-aware horizon check using the cached TX envelope. In version 2.4a, a 500m diffraction tolerance zone is implemented to model knife-edge diffraction and troposcatter.

// ── Beam hard gate ─────────────────────────────────────────
const beamMultAc = getTxBeamScore(tx, acLat, acLon);
if (beamMultAc === 0.0) return null;  // aircraft outside beam → hard reject

const beamMultRx = getTxBeamScore(tx, rxLat, rxLon);
if (beamMultRx === 0.0) return null;  // RX outside beam → hard reject

// Combined beam multiplier applied to final score
const beamMult = beamMultAc * beamMultRx;

// ── Terrain-aware horizon check (envelope cache) ──────────────────
const env    = getTxEnvelope(tx, rxLat, rxLon, rxElevM);

const hrxAtAc = env.hrx_env[idxLo] * (1 - frac) + env.hrx_env[idxHi] * frac;
const htxAtAc = env.htx_env[idxLo] * (1 - frac) + env.htx_env[idxHi] * frac;

// --- NEW: DIFFRACTION TOLERANCE ---
const DIFFRACTION_TOLERANCE_M = 500; // 500m tolerance for knife-edge diffraction/scatter

// Hard cut-off is now pushed 500m below the calculated radio horizon
if (altM < (hrxAtAc - DIFFRACTION_TOLERANCE_M) || altM < (htxAtAc - DIFFRACTION_TOLERANCE_M)) {
    return null;
}

// Calculate how deep the aircraft is in the "shadow" (0 if in direct line of sight)
const shadowDepthTx = Math.max(0, htxAtAc - altM);
const shadowDepthRx = Math.max(0, hrxAtAc - altM);
const maxShadowDepth = Math.max(shadowDepthTx, shadowDepthRx);

// Apply a penalty if the plane relies on diffraction (shadow zone)
// 0m shadow = multiplier 1.0 (no penalty)
// 500m shadow = multiplier 0.2 (heavy penalty, but still valid for the score)
const diffractionMultiplier = 1.0 - (maxShadowDepth / DIFFRACTION_TOLERANCE_M) * 0.8;
// ----------------------------------

const c_factor = 16.974;
const bulgeTx  = (d_tx * d_tx) / c_factor;
const bulgeRx  = (d_rx * d_rx) / c_factor;

// Zurück zur klassischen Winkel-Berechnung
const elevAngleTxDeg = toDeg(Math.atan2((altM - bulgeTx) - env.txEffM, d_tx * 1000));
const elevAngleRxDeg = toDeg(Math.atan2((altM - bulgeRx) - rxElevM,    d_rx * 1000));

if (elevAngleTxDeg > 15 || elevAngleRxDeg > 20) return null;

const txSigma = 2.0, rxSigma = 8.0;
const txElevScore  = Math.exp(-(elevAngleTxDeg * elevAngleTxDeg) / (2 * txSigma * txSigma));
const rxElevScore  = Math.exp(-(elevAngleRxDeg * elevAngleRxDeg) / (2 * rxSigma * rxSigma));

// Apply the new diffraction multiplier to the base sweetSpotScore
const sweetSpotScore = txElevScore * rxElevScore * diffractionMultiplier;

Score formula

let baseScore = sweetSpotScore * 40
              + marginScore    * 20
              + distScore      * 20
              + reflScore      * 10
              + fuseScore      * 5
              + erpScoreVal    * 3
              + (freqFactor - 0.97) / 0.06 * 2;

// beamMult: product of aircraft-side and RX-side beam scores
const finalScore = baseScore * sizeMult * beamMult;

return {
    score: Math.max(0, Math.min(100, Math.round(finalScore))),
    crossTrackKm
};

5.2 · Geometric Helper Functions

Great-circle intersection point

const nTxRx = normalize(cross(vTx, vRx));
const nAc   = normalize(cross(vAcPos, vAcAhead));
const inter = normalize(cross(nTxRx, nAc));
// Two antipodal solutions – pick closest to aircraft
const best = haversineKm(acLat,acLon,p1.lat,p1.lon) <
             haversineKm(acLat,acLon,p2.lat,p2.lon) ? p1 : p2;
// Safety: if outside TX–RX segment, fall back to midpoint
if (haversineKm(best,txLat,txLon) > d_txrx ||
    haversineKm(best,rxLat,rxLon) > d_txrx)
    return midpointGreatCircle(txLat,txLon,rxLat,rxLon);

Cross-track and along-track decomposition

const d13 = haversineKm(aLat,aLon,pLat,pLon);
const angleRad = toRad(normalizeAngle180(t13 - t12));
crossTrackKm  = Math.abs(d13 * Math.sin(angleRad));
alongTrackKm  = d13 * Math.cos(angleRad);

Fuselage alignment score

const optimalTrack =
    ((bTx + normalizeAngle180(bRx - bTx) / 2 + 360) % 360 + 90) % 360;
let trackDiff = Math.abs(normalizeAngle180(acTrackDeg - optimalTrack));
if (trackDiff > 90) trackDiff = 180 - trackDiff;
return 0.3 + 0.7 * Math.max(0, Math.cos(toRad(trackDiff)));

Reflection geometry score

const angleDeg = toDeg(Math.acos(
    Math.max(-1, Math.min(1, dot(i, o)))));
const diff = angleDeg - 40;
reflScore = Math.exp(-(diff * diff) / (2 * 25 * 25));

5.3 · Radio Horizon and Line-of-Sight Gate

Airplane scatter can only occur when neither the transmitter nor the receiver can "see" the other directly, but both can "see" the aircraft. The radio horizon formula uses the standard 4/3-earth approximation:

function radioHorizonKm(h1m, h2m) {
  return 4.12 * (Math.sqrt(Math.max(0, h1m))
               + Math.sqrt(Math.max(0, h2m)));
}

The dynamic ellipse gate grows slightly with altitude:

const dynamicEllipseFactor = 1.02 + Math.min(1.0, altM / 12000) * 0.06;
if (d_tx + d_rx > dynamicEllipseFactor * d_txrx) return null;

5.4 · Persistent Crossing Tracker

Each (aircraft, transmitter) pair that reaches the score threshold is stored in the two-level dictionary _persistentCrossings[icao24][txKey]. This persistence layer ensures that a candidate first detected at −3 minutes remains visible throughout its approach, peak, and recession.

5.5 · Dead Reckoning and Aircraft State

Between 15-second ADS-B updates the plugin uses dead reckoning to estimate each aircraft's current position:

function deadReckonRad(lat, lon, trackDeg, distKm) {
  const d = distKm / 6371;
  const f = toRad(lat), l = toRad(lon), t = toRad(trackDeg);
  const lat2 = Math.asin(Math.sin(f)*Math.cos(d)
                       + Math.cos(f)*Math.sin(d)*Math.cos(t));
  const lon2 = l + Math.atan2(
                       Math.sin(t)*Math.sin(d)*Math.cos(f),
                       Math.cos(d)-Math.sin(f)*Math.sin(lat2));
  return { lat: toDeg(lat2), lon: toDeg(lon2) };
}

Altitude is also extrapolated using the reported vertical speed:

const fAltFt = ac.alt_ft + ((ac.vspeed || 0) / 60) * dtSec;
if (fAltFt < 1000) continue;

5.6 · Elevation Data and Topographic Profile

Terrain elevation data is fetched from two APIs and additionally cached on the server via the new elevation_cache.json feature introduced in v2.4, preventing excessive upstream calls.

The profile is built from 100 equidistant great-circle sample points. Two running envelopes are computed — one from RX and one from TX — representing the minimum flight altitude to be simultaneously visible from both ends.

The purple scatter zone floor at each profile point is max(hrx_arr[i], htx_arr[i]) — the aircraft must be above this to be visible from both ends. In version 2.4a, a two-pass topography check uses this exact array to penalize or hard-reject aircraft that are physically blocked by terrain during the scoring process (allowing a 500m diffraction zone).

5.7 · Sweet Spot Corridor Computation

The Sweet Spot corridor is computed by the function computeSweetSpotCorridor(elevs, d_txrx, rxAltM, txAltM, hrx_arr, htx_arr). It adds two angular ceiling constraints on top of the existing purple zone floor.

The two angle ceilings

const RX_ANGLE_DEG = 5.0;   // aircraft must be ≤ 5° elevation from RX
const TX_ANGLE_DEG = 1.0;   // aircraft must be ≤ 1° elevation from TX

// Ceiling imposed by the RX elevation angle limit
const rxAngleCeil = rxAltM + x    * 1000 * tanRx;

// Ceiling imposed by the TX elevation angle limit
const txAngleCeil = txAltM + d_tx * 1000 * tanTx;

// Sweet spot ceiling = the lower of the two limits
const sweetCeil = Math.min(rxAngleCeil, txAngleCeil);

5.8 · Elevation Profile Hover Tooltip

The function initProfileCanvasHover() attaches a mousemove listener to the profile canvas. When the cursor is inside the plot area, it creates a floating tooltip showing detailed information for the path point directly below the cursor.

5.9 · TX Spatial Grid Index, Envelope Cache & Anti-Stutter

The plugin builds a 10° × 10° spatial grid index over the loaded TX database. For each aircraft, only transmitters in the 9 grid cells surrounding the aircraft position are checked.

TX Terrain Envelope Cache

Each TX envelope is computed once per RX position and stored in a Map keyed by tx.lat_tx.lon_tx.freq. All subsequent evaluations for the same TX reuse the cached result. The cache is invalidated when the RX elevation is refreshed, when a new TX dataset is loaded, after elevation enrichment completes, or when the user applies new settings.

Anti-Stutter Yield

Yield interval: 8 ms trigger, 0 ms sleep (pure event-loop yield via setTimeout(r, 0)). The zero-delay return is sufficient because the envelope cache eliminates most of the computation that previously caused long synchronous stretches.

5.10 · ADS-B Parallel Fetching & Redundancy

The plugin simultaneously queries five public ADS-B aggregators in parallel to ensure maximum coverage and elegantly bypass individual Cloudflare blocks or server outages:

• api.adsb.one
• api.adsb.lol
• api.adsb.fi
• api.airplanes.live
• api.theairtraffic.com

Large radius requests are broken into hexagonal overlapping tile queries because the APIs have a strict maximum radius of 250 Nautical Miles (≈463 km). All five sources are queried simultaneously per tile (using Promise.all). The JSON responses are automatically merged, and any duplicate aircraft are filtered out using their unique ICAO 24-bit addresses. If a source is offline or returns an HTML Cloudflare challenge instead of JSON, the plugin safely ignores it without crashing and continues processing the remaining sources. An explicit 500 ms delay between tile points prevents API rate-limiting.

5.11 · fmdx.org TX Database – Server-Side Cache

The full 50 MB fmdx.org dataset is managed entirely on the server with a four-tier priority cascade:

5.12 · GPS & PST Rotator WebSocket Listener

The plugin integrates with the FM-DX-Webserver ecosystem by listening to two standard WebSockets:

• /data_plugins: Broadcasts GPS updates and PST Rotator azimuth. When the rotor turns, the compass lock (if activated) follows automatically.
• /text: Broadcasts RDS data and frequency changes. When the Frequency Sync Lock is active, the map filters automatically to the current receiver frequency.

5.13 · Country Flag Lookup

Country flags are generated dynamically. The plugin loads a JavaScript array from tef.noobish.eu/logos/scripts/js/countryList.js mapping ITU codes to ISO 2-letter country codes, then generates HTML <img> tags pointing to flagcdn.com. The lookup is cached in localStorage for 24 hours.

5.14 · Compass and Frequency Filters

• Compass Filter: Supports Multi-Select — click multiple directional buttons simultaneously. When the Rotor Sync Lock is active, the compass updates automatically as the antenna turns.
• Frequency Filter: Text input filters the entire database to a specific frequency. Supports static Blacklist/Whitelist files loaded from the server.
• Aircraft Category Filter: Filters out small aircraft based on ADS-B category. Setting to A3+ hides Cessnas and helicopters, reducing clutter.

5.15 · Update Check

On startup, the plugin fetches its own source file from GitHub and compares the pluginVersion constant. If a newer version is found, a red notification dot appears on the plugin icon and a link is injected into the settings panel.

5.16 · Audio Stream Integration (Web Radio)

The TX detail panel includes Play/Stop icons next to each frequency. Clicking Play calls window._asHandleStreamClick() which queries api.fmlist.org/152/fmdxGetStreamById.php (via the local proxy) for stream URLs, selects the highest bitrate, and plays it via a hidden HTML5 <audio> element.

5.17 · Local Node Proxy Server

The airplanescatter_server.js backend attaches to the FM-DX-Webserver HTTP server and exposes two endpoints:

• /api/airplanescatter/fmdx – returns the server-filtered TX station list
• /api/airplanescatter/proxy?url=... – generic HTTPS proxy for ADS-B, elevation, and stream APIs

Key security mechanisms: Caller Guard, Domain Whitelist (only proxies to allowed domains), 10 MB response size cap, and sealResponse() to prevent "headers already sent" conflicts.

5.18 · fmscan.org Userlist Integration (userlist1.csv)

The plugin optionally integrates the userlist1.csv file generated by the fmscan.org FMSCAN Userlist service. This file contains supplementary per-transmitter data that is not available in the standard fmdx.org database, most importantly the main transmitter beam direction and additional RDS metadata.

What is the userlist1.csv?

The fmscan.org service (login required at fmscan.org) allows registered users to generate a personalised CSV file based on their receiver location. The file contains all FM transmitters that are theoretically receivable from the configured QTH, with calculated distance, azimuth, and signal level (dB) for each. By selecting FM+ (Tropo) as the mode and CSV format with semicolon as the separator, and then downloading userlist1.csv, the user gets a file with the following column layout:

How to install the userlist

1. Download userlist1.csv from https://fmscan.org/perseus.php?userlistmode=fm
2. Place the file in the plugin directory: …/fm-dx-webserver-main/plugins/AirplaneScatter/userlist1.csv
3. Restart the FM-DX Webserver
4. Reload the browser — the plugin will automatically detect and load the file on startup.

The file is loaded once at startup by the asynchronous function loadUserlist() and stored in the in-memory dictionary _userlistDb, keyed by the unique transmitter ID (last column). If the file is not present, the plugin continues to work normally using only the fmdx.org data — all userlist features simply remain inactive.

How the userlist data is used

Once loaded, the userlist data enriches the TX station objects in three ways:

• Beam direction enrichment (enrichTxBeamData()): For each TX station loaded from fmdx.org, the function searches for a matching entry in the userlist (matched by frequency + coordinates within 0.01°). If a beam value is found, it is copied to the TX object's beam property. This enables the beam scoring gate in getTxBeamScore().
• Scoring gate (getTxBeamScore()): The beam string is parsed and the bearing to the aircraft and the bearing to the RX are tested against the antenna arc. Non-directional transmitters (no beam data) are treated as omnidirectional and pass with a multiplier of 1.0.
• TX detail panel display: If a userlist entry is found for a selected TX, its RDS PI code, PS name, programme name, language, and polarisation are shown in the detail panel alongside the standard fmdx.org data.

Matching logic

The function getUserlistEntry(tx) first tries to find a match by the numeric transmitter ID. If no ID is stored on the TX object (fmdx.org entries do not carry fmscan IDs), it falls back to a frequency + coordinate search:

function getUserlistEntry(tx) {
    if (!tx) return null;
    // 1. Try direct ID lookup
    if (tx.id && _userlistDb[String(tx.id)])
        return _userlistDb[String(tx.id)];

    // 2. Fallback: frequency + coordinate match
    const freqKhz = Math.round(tx.freq * 1000);
    return Object.values(_userlistDb).find(e =>
        parseInt(e.khz, 10) === freqKhz &&
        Math.abs(parseFloat(e.lat) - parseFloat(tx.lat)) < 0.01 &&
        Math.abs(parseFloat(e.lon) - parseFloat(tx.lon)) < 0.01
    ) || null;
}

5.19 · Transmitter Beam Direction Score

The TX beam direction is a fully functional hard gate and score multiplier, powered by the userlist1.csv data. The function getTxBeamScore(tx, targetLat, targetLon) returns a value between 0.0 (hard reject) and 1.0 (full score) for a given target direction from the transmitter.

Beam string formats

The userlist beam field (beam) can contain two formats:

Scoring logic

function getTxBeamScore(tx, targetLat, targetLon) {
    // Look up beam string: first from this tx, then from siblings
    let beamStr = (tx.beam || '').trim();
    if (!beamStr) {
        const sibs = txSiblings(tx);
        for (const sib of sibs) {
            const sibBeam = (sib.beam || '').trim();
            if (sibBeam) { beamStr = sibBeam; break; }
        }
    }
    if (!beamStr) return 1.0;  // omnidirectional – no data

    const brg = bearingDeg(tx.lat, tx.lon, targetLat, targetLon);
    const isRange = /^\d+\s*-\s*\d+$/.test(beamStr);

    if (isRange) {
        // Range beam: e.g. "270-40" means arc from 270° to 40°
        // Returns 1.0 inside arc, linear fade over 3° outside, 0.0 beyond
        const inRange = /* ... wrapping check ... */;
        if (inRange) return 1.0;
        if (outsideDeg >= 3) return 0.0;
        return 1.0 - (outsideDeg / 3);
    } else {
        // Single / multi heading: ±30° half-beamwidth, hard reject at 40°
        const outsideDeg = Math.max(0, minDist - 30);
        if (outsideDeg >= 10) return 0.0;
        return 1.0 - (outsideDeg / 10);
    }
}

How the beam gate is applied

The function is called twice per (aircraft, TX) pair inside _evalScatterAt():

1. Aircraft direction gate: The bearing from the TX to the aircraft's current position is checked against the beam. If the aircraft is outside the illuminated arc, the TX cannot scatter energy toward it at all — hard reject.
2. RX direction gate: The bearing from the TX to the receiver is also checked. Even if the aircraft is inside the beam, scatter can only reach the RX if the TX also illuminates the direction toward the RX — hard reject if not.

The two individual beam scores are then multiplied together and applied to the final score:

const finalScore = baseScore * sizeMult * beamMult;
// beamMult = beamMultAc × beamMultRx  (both must be > 0)

Transmitters for which no beam data is available (either not in the userlist, or beam field is empty) are treated as omnidirectional — the gate always passes and the multiplier is 1.0. This means that the userlist1.csv only ever reduces scores or hard-rejects candidates; it never increases them above the base value.

Sibling beam lookup

The fmdx.org database lists each frequency at a transmitter site as a separate entry. When beam data is looked up for a given TX entry and the entry itself has no beam field, the function also searches all co-located entries at the same geographic position (same latitude/longitude within 0.001°) — the "siblings" — and uses the first beam value found. This is important because a transmitter site may have beam data attached only to one of its frequency entries in the userlist.

6 · Configuration Parameters

The plugin contains several hardcoded parameters at the top of airplanescatter.js that determine the physical and visual bounds of the simulation.

// Forecast steps in seconds – 5 steps, 5-minute look-ahead
const FORECAST_STEPS_SEC  = [0, 60, 120, 180, 300];

// Maximum time before missing aircraft is discarded
const AIRCRAFT_TIMEOUT_MS = 180000; // 3 minutes

// ADS-B fetch interval
const AIRCRAFT_UPDATE_MS  = 15000;  // 15 seconds

// Visual countdown ticker interval
const COUNTDOWN_TICK_MS   = 1000;   // 1 second

// TX database cache duration
const DB_CACHE_HOURS      = 24;

// Score colour thresholds
const SCORE_EXCELLENT     = 80;
const SCORE_HIGH          = 60;
const SCORE_MEDIUM        = 40;

// TX antenna height above terrain (default if not in DB)
const TX_HEIGHT_DEFAULT_M = 150;

// ADS-B pre-filter radius
const AC_PREFILTER_KM     = 1200;
const AC_PREFILTER_LATDEG = 11.0;

7 · User Settings

The settings panel (⚙ button) exposes the following parameters. All values are saved to localStorage and persist across browser sessions.

7.1 · Blacklist and Whitelist Configuration

Place plain text files in the plugins/AirplaneScatter/ directory on the server:

• blacklist.txt – frequencies to exclude (one per line, e.g. 98.00)
• whitelist.txt – frequencies to include exclusively (all others hidden)

Lines starting with # are treated as comments and ignored. Both comma and period are accepted as decimal separators. Only values in the FM broadcast range (87.5–108.0 MHz) are accepted.

7.2 · userlist1.csv – fmscan.org Beam & RDS Data

The userlist1.csv file provides beam directions and supplementary RDS data for transmitters in the vicinity of your receiver. It is generated specifically for your receiver location by fmscan.org and must be placed in the plugin directory.

Download instructions

1. Create a free account at fmscan.org and log in.
2. Make sure your receiver location (QTH) is correctly configured in your fmscan.org account.
3. Navigate to FMSCAN → Tools (userlist etc.) → Perseus / Globaltuners / SDR Console Location Search.
4. Select: mode = FM+ (Tropo), CSV Separator = semicolon, format = CSV format.
5. Click DOWNLOAD userlist1.csv and wait approximately one minute for the file to be generated.
6. Place the downloaded file at: …/fm-dx-webserver-main/plugins/AirplaneScatter/userlist1.csv
7. Reload the browser. The plugin will automatically detect and load the file.

8 · Recommended Companion Plugins

9 · Tips, Tricks & Best Practices

• Watch the Sweet Spot, not just the score. A score of 70% means little if the aircraft dot in the profile is far outside the green corridor. The green band is the single best visual indicator of whether scatter will be strong.
• Use the frequency lock. Lock the frequency filter to your current receiver frequency. This hides all TX stations not on that frequency and reduces visual clutter to only the candidates that matter right now.
• Pre-tune using the webstream. Click the audio stream Play button in the TX detail panel a minute before the predicted crossing. You will hear the distant station on its stream and can compare it to what you hear on the radio during the event.
• Set lead time to at least 3 minutes. Wide-body jets travel at ~900 km/h. A 3-minute lead gives about 45 km of advance warning — enough time to tune and prepare.
• Use the elevation profile hover tooltip to verify that the aircraft's elevation angle from the TX is ≤ 1° as it approaches the Sweet Spot. This is the clearest sign of an imminent strong event.
• On low-power hardware (Raspberry Pi, Intel Compute Stick): reduce TX radius to 500 km and aircraft radius to 500 km to reduce the number of (aircraft, TX) pairs processed. Version 2.1a already reduces CPU load by ~70% through the envelope cache and pre-filter.
• The first startup after installation will download and cache the TX database. Subsequent starts use the cached version. The cache is valid for 24 hours or until the RX QTH changes by more than 100 km.
• Use the userlist1.csv for beam-aware scoring. If you have an fmlist.org account, download your personalised userlist1.csv from https://fmscan.org/perseus.php?userlistmode=fm (select CSV format with semicolon separator) and place the file in the plugins/AirplaneScatter/ directory on the server. The plugin will then use the beam direction data to suppress off-beam transmitters and display additional station metadata (PI code, PS name, RDS programme name) in the TX detail panel. This can significantly reduce false positives from highly directional transmitters.
• Beam data interpretation: A transmitter with a narrow beam pointing away from your receiver will now score zero for that direction, even if its ERP and geometry would otherwise qualify it as a candidate. This is physically correct: a directional antenna cannot produce usable scatter in a direction it does not radiate.
• If the userlist1.csv is absent, all transmitters are treated as omnidirectional (beam score = 1.0). The file is entirely optional.

10 · Changelog

Version 2.4a – May 2026 Current

• Knife-Edge Diffraction Tolerance: Added a 500-meter tolerance zone below the radio horizon to account for troposcatter and mountain diffraction. Aircraft slightly shadowed by terrain are no longer hard-rejected but instead receive a proportional shadow penalty to their score.
• Increased Default TX Radius: Default txRadiusKm increased from 750 km to 1200 km to better capture distant transmitters for high-altitude scatter events.

Version 2.4 – May 2026

• Min TX ERP: Enables a minimum TX ERP of less than 1 kW.
• UI/Responsiveness: Full-screen detection optimized for tablets.
• Bugfix: Functionality and positioning of the "Close" (X) button corrected in the settings panel.

Version 2.3b – April 2026

• Local Elevation Cache: Created a server-side elevation_cache.json to locally cache topographic data fetched from APIs. This permanently reduces API rate limit issues and significantly speeds up path elevation lookups.
• Topographic Scoring Exclusion (Two-Pass Validation): Implemented a two-pass terrain validation algorithm in the core scoring engine. Aircraft that reside physically below the horizon line due to real mountain terrain are now accurately excluded during the initial scoring phase. This effectively eliminates terrain-blocked false positives.
• Added fallback support to the Open-Elevation API if OpenTopoData fails or rate-limits, further improving data reliability.

Version 2.3a – April 2026

• Airplane Photo display can now be enabled and disabled in the settings.
• Function to automatically move the web server to the right added to the settings (thanks to bojcha for the idea & code).

Version 2.3 – April 2026

• Important performance improvements, audio dropouts fixed.
• Added additional sweet spot marker to the map.
• Added display of airplane photos.

Version 2.2 – April 2026

Feature release adding optional beam-aware TX scoring via a personalised fmlist.org userlist, additional station metadata display, and two bug fixes.

New Features

• userlist1.csv integration — beam-aware scoring and enhanced metadata: The plugin now optionally loads a file named userlist1.csv from the plugins/AirplaneScatter/ directory on the server. This file is a personalised transmitter database generated by the fmlist.org service (registration required) and can be downloaded from https://fmscan.org/perseus.php?userlistmode=fm by selecting CSV format with semicolon separator and clicking DOWNLOAD userlist1.csv.
  CSV field layout (semicolon-separated):
  khz ; country ; language ; program ; modulation ; location ; latitude ; longitude ; power_to_rx ; max_erp ; beam ; distance ; azimuth ; dB ; RDS_PS ; RDS_PI ; polarisation ; ID
  
  The beam field (column 11, zero-indexed) contains either a single azimuth value (e.g. 200), a range (e.g. 270-40), or is empty for omnidirectional transmitters. The ID field (last column) is the unique fmlist station identifier used to match entries to the fmdx.org TX database.
  When userlist1.csv is present and successfully loaded, the plugin:
  • Enriches each TX station object with its beam direction string from the CSV, matched by fmlist ID or by frequency + coordinates.
  • Applies a beam gate in getTxBeamScore(): any TX whose beam does not cover both the aircraft position and the RX direction receives a score multiplier of 0.0 and is hard-rejected from the candidate list.
  • Applies a beam pre-filter in computePersistentCrossings() before the expensive full scatter calculation, eliminating clearly off-beam TX stations with two fast angular comparisons.
  • Displays additional station metadata in the TX detail panel and map tooltips: RDS PI code, RDS PS name, programme name, and power-towards-receiver value from the userlist.
• Beam scoring logic details:
  • Range beam (e.g. 270-40, meaning 270° clockwise to 40°): If the target bearing is within the arc → score 1.0. If outside by up to 3° → linear taper from 1.0 to 0.0. If outside by ≥ 3° → hard reject (score 0.0).
  • Single-value beam (e.g. 200, optionally multiple values): ±30° half-beamwidth assumed. Outside the 30° half-width by up to 10° → linear taper. Outside by ≥ 10° → hard reject (score 0.0).
  • Beam score is computed independently for the aircraft direction (TX → AC) and the RX direction (TX → RX). Both must be non-zero; the final beam multiplier is their product.
  • If no beam data is found for a TX station (neither in tx.beam nor in any co-located sibling) → beam score defaults to 1.0 (omnidirectional treatment).

Bug Fixes

• Compass filter — E and NE direction mapping corrected: In v2.1a the bearing ranges for the East (E) and North-East (NE) compass buttons were swapped due to an off-by-one error in the getActiveVisibleCrossings() direction lookup table. As a result, clicking E filtered to the NE quadrant and vice versa. The correct ranges are now:
  • NE: 22.5° – 67.5°
  • E: 67.5° – 112.5°
  All other compass directions were unaffected.
• WebSocket connection counter — plugin connection no longer counted as a listener: The plugin's own internal WebSocket connections to /data_plugins and /text were previously included in the FM-DX-Webserver's active listener count, inflating the displayed connection number by up to 2. The plugin now correctly identifies its connections so that they are excluded from the server's client counter.
• CSV parse error "Transmitter ID not found in CSV" resolved: The loadUserlist() parser previously used a hardcoded field index (f[17]) for the station ID. Lines in the fmlist CSV that contain more than 18 semicolon-separated fields (e.g. entries with additional optional columns) caused the ID to be read from the wrong position, resulting in the error "Transmitter ID not found in CSV". The parser now always reads the ID from f[f.length - 1] (the last field), correctly handling variable-width rows.

Internal Changes

• New functions: loadUserlist(), getUserlistEntry(), enrichTxBeamData(), getTxBeamScore() added to the client plugin.
• Startup sequence: loadUserlist() is called once during plugin initialisation, before the first TX database load. enrichTxBeamData() is called after txStations is populated (or reloaded), adding beam data to all matched TX entries without a second network request.
• Beam pre-filter in crossing tracker: When tx.beam is set, computePersistentCrossings() evaluates both beam gates before calling calcScatter(), avoiding the more expensive envelope and scoring pipeline for off-beam transmitters.

Version 2.1a – April 2026

Performance optimisation release targeting low-power hardware (Intel Compute Stick, Raspberry Pi class devices). No functional or visual changes — all existing features and the UI remain identical to v2.1.

• TX terrain envelope cache: The Float64Array horizon envelopes for each transmitter are now computed once per RX position and reused for all aircraft. Cache is invalidated on RX position change, TX database reload, after elevation enrichment, and when settings are applied. Reduces per-cycle CPU time by approximately 60–80%.
• Cheap pre-filter in crossing tracker: A Haversine-only pre-filter in computePersistentCrossings() eliminates ~60% of (aircraft, TX) pairs before the full scoring function is invoked.
• Reduced forecast steps: FORECAST_STEPS_SEC reduced from 11 steps to 5 steps ([0, 60, 120, 180, 300]).
• Early-exit in score loop: The forecast loop breaks immediately when a score ≥ 95 is found.
• 10° spatial grid: TX grid cell size doubled from 5° to 10°.
• Hash-based profile redraw guard: The elevation profile canvas is skipped when the aircraft set and ETA buckets have not changed since the last draw.
• Tighter anti-stutter yield: Yield interval changed from 10 ms / 5 ms sleep to 8 ms / 0 ms.
• Settings apply fix: invalidateTxEnvelopeCache() is called when settings are applied.

Version 2.1 – April 2026

• Server-side TX database (Priority 1–4 cascade).
• Sweet Spot corridor in elevation profile.
• Profile hover tooltip with elevation angles.
• Sweet Spot scoring — core function rewritten.
• Terrain-aware horizon gate in _evalScatterAt().
• Aircraft category type filter.
• Frequency blacklist/whitelist.
• PST Rotator Compass Sync.
• Frequency Sync Lock.
• Web radio stream integration.
• Country flag display.
• Profile canvas interactivity (zoom, pan, vertical scale).