ADS-B

ADS-B (Automatic Dependent Surveillance-Broadcast) is an aircraft automatic broadcast system. The SDK provides complete ADS-B functionality support, including aircraft position display, heading rotation, data interpolation, etc.

Features

• Aircraft Position Display: Real-time display of aircraft positions
• Heading Rotation: Aircraft icons automatically rotate based on heading
• Aircraft Labels: Display aircraft call signs or identifiers
• Data Interpolation: Supports position interpolation for smooth aircraft movement display
• Performance Optimization: Intelligent display based on zoom level and view range

Basic Usage

Enable ADS-B Function

// Basic enable (without interpolation)
sdk.adsb.open();

// Enable with interpolation
sdk.adsb.open({}, {}, true);

Update Aircraft Data

// Prepare aircraft data
const features = [
  {
    type: "Feature",
    geometry: {
      type: "Point",
      coordinates: [116.3974, 39.9093], // [longitude, latitude]
    },
    properties: {
      heading: 90,           // Heading (degrees)
      speed: 500,            // Speed (knots)
      time_stamp: "2025-01-01T12:00:00Z", // Timestamp
      callsign: "CA1234",    // Call sign
      aircraft_id: "B-1234", // Aircraft ID
      icao: "780123",        // ICAO code
      id: "aircraft-1",      // Unique identifier
      label: "CA1234",       // Display label (optional)
    },
  },
  // More aircraft data...
];

// Update aircraft data
sdk.adsb.update(features);

Close ADS-B Function

sdk.adsb.close();

Complete Examples

Example 1: Basic Usage

let sdk;

async function initMap() {
  sdk = new navMap.MapSDK({
    container: "map",
    center: [116.39, 39.9],
    zoom: 10,
  });

  sdk.on("loadComplete", () => {
    setupADSB();
  });
}

function setupADSB() {
  // Enable ADS-B function
  sdk.adsb.open();

  // Simulate aircraft data
  const aircrafts = [
    {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [116.3974, 39.9093],
      },
      properties: {
        heading: 90,
        speed: 500,
        callsign: "CA1234",
        aircraft_id: "B-1234",
        time_stamp: new Date().toISOString(),
      },
    },
  ];

  // Update aircraft data
  sdk.adsb.update(aircrafts);
}

initMap();

Example 2: WebSocket Real-time Updates

let sdk;
let ws;

function setupADSB() {
  // Enable ADS-B function with interpolation
  sdk.adsb.open({}, {}, true);

  // Connect WebSocket
  const wsUrl = "ws://your-server.com/adsb";
  ws = new WebSocket(wsUrl);

  ws.onopen = () => {
    console.log("ADS-B WebSocket connected");
  };

  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    
    // Convert data format
    const features = data.aircrafts.map((aircraft) => ({
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [aircraft.lng, aircraft.lat],
      },
      properties: {
        heading: aircraft.heading,
        speed: aircraft.speed,
        callsign: aircraft.callsign,
        aircraft_id: aircraft.id,
        time_stamp: aircraft.timestamp,
        id: aircraft.id,
      },
    }));

    // Update aircraft data
    sdk.adsb.update(features);
  };

  ws.onerror = (error) => {
    console.error("WebSocket error:", error);
  };

  ws.onclose = () => {
    console.log("WebSocket connection closed");
  };
}

// Close connection on page unload
window.addEventListener("beforeunload", () => {
  if (ws) {
    ws.close();
  }
  if (sdk) {
    sdk.adsb.close();
  }
});

Example 3: Custom Layer Styles

// Custom aircraft icon style
const pointLayerConfig = {
  layout: {
    "icon-image": "custom-aircraft-icon", // Custom icon
    "icon-size": [
      "interpolate",
      ["linear"],
      ["zoom"],
      2, 0.4,
      8, 0.6,
      12, 0.8,
    ],
    "icon-rotate": ["get", "heading"],
    "icon-rotation-alignment": "map",
  },
};

// Custom label style
const labelLayerConfig = {
  show: true, // Whether to show label
  layout: {
    "text-field": ["get", "callsign"],
    "text-size": 14,
    "text-offset": [0.8, 0],
    "text-anchor": "left",
  },
  paint: {
    "text-color": "#000000",
    "text-halo-color": "#ffffff",
    "text-halo-width": 2,
  },
};

// Enable ADS-B function
sdk.adsb.open(pointLayerConfig, labelLayerConfig, true);

API Reference

open()

Enable ADS-B function.

Parameters:

• pointLayerConfig (optional): Aircraft icon layer configuration
• labelLayerConfig (optional): Aircraft label layer configuration
• enableInterpolation (optional): Whether to enable position interpolation, default false

Example:

sdk.adsb.open(
  {
    layout: {
      "icon-size": 0.6,
    },
  },
  {
    show: true,
  },
  true
);

update()

Update aircraft data.

Parameters:

• features (Array): Aircraft data array, each element is a GeoJSON Feature object

Feature Format:

{
  type: "Feature",
  geometry: {
    type: "Point",
    coordinates: [longitude, latitude],
  },
  properties: {
    heading: number,        // Heading (degrees, 0-360)
    speed: number,          // Speed (knots)
    time_stamp: string,     // Timestamp (ISO 8601 format)
    callsign: string,       // Call sign (optional)
    aircraft_id: string,    // Aircraft ID (optional)
    icao: string,          // ICAO code (optional)
    id: string,            // Unique identifier (required)
    label: string,         // Display label (optional, takes priority over callsign)
  },
}

Example:

sdk.adsb.update([
  {
    type: "Feature",
    geometry: {
      type: "Point",
      coordinates: [116.3974, 39.9093],
    },
    properties: {
      heading: 90,
      speed: 500,
      callsign: "CA1234",
      id: "aircraft-1",
      time_stamp: "2025-01-01T12:00:00Z",
    },
  },
]);

close()

Close ADS-B function, clean up all layers and data.

Example:

sdk.adsb.close();

Data Interpolation

Enable Interpolation

After enabling interpolation, the SDK will automatically calculate aircraft positions based on speed, heading, and timestamp for smooth movement effects.

// Enable interpolation
sdk.adsb.open({}, {}, true);

Interpolation Features

• Auto Interpolation: Automatically calculates aircraft position once per second
• Smart Merging: Intelligently merges when new data arrives, maintaining movement continuity
• Level Control: Automatically disables interpolation when zoom level is below 8
• Timeout Stop: Automatically stops interpolation when no new data for over 60 seconds

Interpolation Configuration

Interpolation automatically adjusts based on the following factors:

• Zoom Level: Disabled when below level 8
• View Range: Only interpolates aircraft within view
• Data Updates: Restarts interpolation when new data arrives

Performance Optimization

Zoom Level Optimization

Aircraft icon size automatically adjusts based on zoom level:

// Default configuration
"icon-size": [
  "interpolate",
  ["linear"],
  ["zoom"],
  2, 0.4,  // Size 0.4 at zoom level 2
  8, 0.5,  // Size 0.5 at zoom level 8
]

Notes

1. Data Format: Ensure aircraft data conforms to GeoJSON Feature format
2. Timestamp: When interpolation is enabled, time_stamp field is important for position calculation
3. Unique Identifier: Each aircraft must have a unique id or aircraft_id
4. Performance Considerations: For large numbers of aircraft, recommend enabling interpolation and view optimization
5. Icon Resources: When using custom icons, icons must be registered first

Common Questions

Q: Aircraft icons not displaying?

A: Check the following:

• Whether open() method was called
• Whether data format is correct
• Whether aircraft is within current view range

Q: Aircraft icons not rotating?

A: Ensure properties.heading field exists and is valid (0-360 degrees)

Q: How to customize aircraft icons?

A: Register icon first, then pass configuration in open():

// Register icon
sdk.registerIcon("custom-aircraft", iconImage, {
  pixelRatio: 1,
});

// Use custom icon
sdk.adsb.open({
  layout: {
    "icon-image": "custom-aircraft",
  },
});

Q: Interpolation not working?

A: Check:

• Whether interpolation is enabled (third parameter is true)
• Whether zoom level is greater than or equal to 8
• Whether data contains time_stamp field