坤舆航图SDK对接指南

简体中文

English

简体中文

English

Appearance

ADS-B ​

ADS-B（Automatic Dependent Surveillance-Broadcast）是一种飞机自动广播系统，SDK 提供了完整的 ADS-B 功能支持，包括飞机位置显示、航向旋转、数据推算等。

功能特性 ​

  • 飞机位置显示：实时显示飞机位置
  • 航向旋转：飞机图标根据航向自动旋转
  • 飞机标签：显示飞机呼号或标识
  • 数据推算：支持位置推算，平滑显示飞机移动
  • 性能优化：根据缩放级别和视野范围智能显示

基础用法 ​

开启 ADS-B 功能 ​

javascript
// 基础开启（不启用推算）
sdk.adsb.open();

// 开启并启用推算功能
sdk.adsb.open({}, {}, true);

更新飞机数据 ​

javascript
// 准备飞机数据
const features = [
  {
    type: "Feature",
    geometry: {
      type: "Point",
      coordinates: [116.3974, 39.9093], // [经度, 纬度]
    },
    properties: {
      heading: 90,           // 航向（度）
      speed: 500,            // 速度（节）
      time_stamp: "2025-01-01T12:00:00Z", // 时间戳
      callsign: "CA1234",    // 呼号
      aircraft_id: "B-1234", // 飞机ID
      icao: "780123",        // ICAO编码
      id: "aircraft-1",      // 唯一标识
      label: "CA1234",       // 显示标签（可选）
    },
  },
  // 更多飞机数据...
];

// 更新飞机数据
sdk.adsb.update(features);

关闭 ADS-B 功能 ​

javascript
sdk.adsb.close();

完整示例 ​

示例1：基础使用 ​

javascript
let sdk;

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

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

function setupADSB() {
  // 开启 ADS-B 功能
  sdk.adsb.open();

  // 模拟飞机数据
  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(),
      },
    },
  ];

  // 更新飞机数据
  sdk.adsb.update(aircrafts);
}

initMap();

示例2：WebSocket 实时更新 ​

javascript
let sdk;
let ws;

function setupADSB() {
  // 开启 ADS-B 功能，启用推算
  sdk.adsb.open({}, {}, true);

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

  ws.onopen = () => {
    console.log("ADS-B WebSocket 连接成功");
  };

  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    
    // 转换数据格式
    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,
      },
    }));

    // 更新飞机数据
    sdk.adsb.update(features);
  };

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

  ws.onclose = () => {
    console.log("WebSocket 连接关闭");
  };
}

// 页面卸载时关闭连接
window.addEventListener("beforeunload", () => {
  if (ws) {
    ws.close();
  }
  if (sdk) {
    sdk.adsb.close();
  }
});

示例3：自定义图层样式 ​

javascript
// 自定义飞机图标样式
const pointLayerConfig = {
  layout: {
    "icon-image": "custom-aircraft-icon", // 自定义图标
    "icon-size": [
      "interpolate",
      ["linear"],
      ["zoom"],
      2, 0.4,
      8, 0.6,
      12, 0.8,
    ],
    "icon-rotate": ["get", "heading"],
    "icon-rotation-alignment": "map",
  },
};

// 自定义标签样式
const labelLayerConfig = {
  show: true, // 是否显示标签
  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,
  },
};

// 开启 ADS-B 功能
sdk.adsb.open(pointLayerConfig, labelLayerConfig, true);

API 参考 ​

open() ​

开启 ADS-B 功能。

参数：

  • pointLayerConfig (可选): 飞机图标图层配置
  • labelLayerConfig (可选): 飞机标签图层配置
  • enableInterpolation (可选): 是否启用位置推算，默认 false

示例：

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

update() ​

更新飞机数据。

参数：

  • features (Array): 飞机数据数组，每个元素是一个 GeoJSON Feature 对象

Feature 格式：

javascript
{
  type: "Feature",
  geometry: {
    type: "Point",
    coordinates: [longitude, latitude],
  },
  properties: {
    heading: number,        // 航向（度，0-360）
    speed: number,          // 速度（节）
    time_stamp: string,     // 时间戳（ISO 8601 格式）
    callsign: string,       // 呼号（可选）
    aircraft_id: string,    // 飞机ID（可选）
    icao: string,          // ICAO编码（可选）
    id: string,            // 唯一标识（必需）
    label: string,         // 显示标签（可选，优先于callsign）
  },
}

示例：

javascript
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() ​

关闭 ADS-B 功能，清理所有图层和数据。

示例：

javascript
sdk.adsb.close();

数据推算 ​

启用推算 ​

启用推算功能后，SDK 会根据飞机的速度、航向和时间戳自动推算飞机位置，实现平滑的移动效果。

javascript
// 启用推算
sdk.adsb.open({}, {}, true);

推算特性 ​

  • 自动推算：每秒自动推算一次飞机位置
  • 智能合并：新数据到达时智能合并，保持移动连续性
  • 层级控制：缩放级别低于8时自动禁用推算
  • 超时停止：超过60秒无新数据时自动停止推算

推算配置 ​

推算功能会根据以下因素自动调整：

  • 缩放级别：低于8级时禁用推算
  • 视野范围：只推算视野内的飞机
  • 数据更新：新数据到达时重新开始推算

性能优化 ​

缩放级别优化 ​

飞机图标大小会根据缩放级别自动调整：

javascript
// 默认配置
"icon-size": [
  "interpolate",
  ["linear"],
  ["zoom"],
  2, 0.4,  // 缩放级别2时大小为0.4
  8, 0.5,  // 缩放级别8时大小为0.5
]

注意事项 ​

  1. 数据格式：确保飞机数据符合 GeoJSON Feature 格式
  2. 时间戳：启用推算时，time_stamp 字段很重要，用于计算位置
  3. 唯一标识：每个飞机必须有唯一的 id 或 aircraft_id
  4. 性能考虑：大量飞机时建议启用推算和视野优化
  5. 图标资源：使用自定义图标时需要先注册图标

常见问题 ​

Q: 飞机图标不显示？ ​

A: 检查以下几点：

  • 是否调用了 open() 方法
  • 数据格式是否正确
  • 飞机是否在当前视野范围内

Q: 飞机图标不旋转？ ​

A: 确保 properties.heading 字段存在且有效（0-360度）

Q: 如何自定义飞机图标？ ​

A: 先注册图标，然后在 open() 时传入配置：

javascript
// 注册图标
sdk.registerIcon("custom-aircraft", iconImage, {
  pixelRatio: 1,
});

// 使用自定义图标
sdk.adsb.open({
  layout: {
    "icon-image": "custom-aircraft",
  },
});

Q: 推算功能不工作？ ​

A: 检查：

  • 是否启用了推算（第三个参数为 true）
  • 缩放级别是否大于等于8
  • 数据中是否包含 time_stamp 字段

Copyright © China Aviation Navigation Data Co., Ltd All Rights Reserved