aviation-chart 0.2.0 → 0.2.1

package/README.md

@@ -1,286 +1,170 @@
-# MapLibre SDK
+# Kunyu Aviation Chart SDK
 
-轻量地图 SDK，采用现代化架构设计，支持插件系统、性能优化和错误处理。
+A high-performance aviation chart SDK providing complete aeronautical data visualization: FIR/UIR, controlled and restricted airspace, airways, navaids (VOR/NDB), airports and runways, AMM, and terrain — plus business features such as NOTAM, ADS-B, and weather radar. Built with a modular architecture supporting plugins, performance optimization, and unified error handling.
 
-## ✨ 新特性
+## ✨ Features
 
-### 🏗️ 架构重构
-- **依赖注入**: 采用接口抽象和依赖注入，提高代码可测试性和可维护性
-- **模块化设计**: 清晰的管理器分离，每个功能模块独立管理
-- **插件系统**: 支持自定义插件扩展，灵活的功能扩展机制
+- **Aviation data stack**: FIR, controlled/restricted airspace, airways, VOR/NDB, airport runways, AMM, terrain/contours — published per AIRAC period
+- **Theme switching**: in-place light/dark recoloring that never covers your overlay layers
+- **Business modules**: NOTAM, ADS-B, weather radar, raster layers
+- **Performance**: LOD (level-of-detail), lazy layer loading, massive-point clustering, low-zoom style simplification
+- **Plugin system**: unified plugin interface with a built-in measurement plugin
+- **Unified error handling**: centralized error management, fallback strategies, error statistics
 
-### 🚀 性能优化
-- **LOD机制**: 基于缩放级别的图层细节层次管理
-- **懒加载**: 图层按需加载，提升初始化和运行性能
-- **聚类支持**: 大数据量点的智能聚合显示
-- **样式优化**: 根据缩放级别自动简化图层样式
+## 🚀 Getting Started
 
-### 🛡️ 错误处理
-- **统一错误管理**: 集中的错误处理和日志记录
-- **错误边界**: 防止单个错误影响整个系统
-- **降级策略**: 智能的错误恢复和降级处理
-- **错误统计**: 详细的错误分析和统计信息
-
-### 🔌 插件系统
-- **标准接口**: 统一的插件开发接口
-- **生命周期管理**: 插件的安装、卸载和状态管理
-- **示例插件**: 内置测量工具插件，展示插件开发模式
-
-## 🚀 快速开始
-
-### UMD 使用
+### Option 1: CDN script (global `navMap`)
 
 ```html
-<link href="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.css" rel="stylesheet" />
-<script src="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.js"></script>
-<script src="/dist/maplibre-sdk.umd.js"></script>
+<!-- latest -->
+<script src="https://aips.siniswift.com/sdk/nav-sdk.min.js"></script>
+<!-- or pin a version -->
+<!-- <script src="https://aips.siniswift.com/sdk/nav-sdk@0.2.0.min.js"></script> -->
 
 <div id="map" style="width:100%;height:600px;"></div>
 
 <script>
-  const sdk = new SDK.MapSDK({
+  const sdk = new navMap.MapSDK({
     container: 'map',
-    style: 'https://demotiles.maplibre.org/style.json',
     center: [116.3974, 39.9093],
-    zoom: 10,
-    errorHandler: (error) => console.error('SDK Error:', error),
-    performance: {
-      lodEnabled: true,
-      clusteringEnabled: true,
-      lazyLoadingEnabled: true
-    }
+    zoom: 4,
+    theme: 'light',        // 'light' | 'dark'
+    period: '202606',      // AIRAC period; auto-computed if omitted
   });
 </script>
 ```
 
-### ESM 使用
+> The underlying map engine is bundled into `nav-sdk.min.js` — no extra script needed.
+
+### Option 2: npm
+
+```bash
+npm install aviation-chart
+```
 
 ```javascript
-import { MapSDK, MeasurePlugin } from 'maplibre-sdk';
+import { MapSDK, MeasurePlugin } from 'aviation-chart';
 
-const sdk = new MapSDK({ 
+const sdk = new MapSDK({
   container: 'map',
-  errorHandler: handleError,
-  performance: { lodEnabled: true }
+  center: [116.3974, 39.9093],
+  zoom: 4,
+  performance: { lodEnabled: true, clusteringEnabled: true, lazyLoadingEnabled: true },
 });
-
-// 使用插件
-const measurePlugin = new MeasurePlugin();
-sdk.use(measurePlugin);
 ```
 
-## 📚 API 概览
+## 📚 API Overview
+
+### Initialization options
 
-### 核心功能
+| Option | Description |
+|---|---|
+| `container` | Container id or element (required) |
+| `center` / `zoom` | Initial center and zoom |
+| `theme` | `'light'` / `'dark'` |
+| `period` | AIRAC period `YYYYMM` |
+| `apiUrl` | Chart data service URL, default `https://aips.siniswift.com` |
+| `layers` | Initial layer visibility, e.g. `{ airspace: true, controlled: false, terrain: false }` |
+| `performance` | `{ lodEnabled, clusteringEnabled, lazyLoadingEnabled }` |
+| `errorHandler` | Custom error handler function |
 
-- **地图初始化**: `new MapSDK(options)` - 支持错误处理和性能配置
-- **错误处理**: `errorHandler` 配置，自动错误捕获和处理
-- **性能优化**: `performance` 配置，支持LOD、聚类、懒加载
+### Layer control
 
-### 图层管理
+Layer groups: `airspace` (FIR), `airline` (airways), `controlled`, `restricted`, `vor`, `ndb`, `airport`, `runway`, `adiz`, `waypointOffAirway`, `amm`, `terrain`, `contour`, `background`, `landLayer`, `boundary`.
 
 ```javascript
-// 基础操作
-await sdk.addBuiltInLayer('水系');
-sdk.removeBuiltInLayer('道路网络');
-sdk.toggleBuiltInLayer('行政边界');
+// Two equivalent APIs
+sdk.setLayerVisible('airspace', true);
+sdk.addBuiltInLayer('controlled');
+sdk.toggleBuiltInLayer('airline');
+sdk.removeBuiltInLayer('restricted');
 
-// 性能优化
+// Theme and period
+sdk.setTheme('dark');
+sdk.setPeriod('202609');
+
+// LOD
 sdk.layerManager.setLODEnabled(true);
-sdk.layerManager.setLayerLODConfig('layerId', {
-  minZoom: 10,
-  maxZoom: 18,
-  minPixelSize: 10,
-  maxPixelSize: 100,
-  cullingEnabled: true
-});
 ```
 
-### GeoJSON 操作
+### Feature drawing (GeoJSON)
 
 ```javascript
-// 添加要素
 sdk.addPoint([lng, lat], properties, style);
 sdk.addLine(coordinates, properties, style);
 sdk.addPolygon(coordinates, properties, style);
 
-// 性能优化
+// Cluster massive point sets
 sdk.geoJSONManager.setClusteringEnabled(true);
-sdk.geoJSONManager.setClusteringConfig('layerId', {
-  enabled: true,
-  radius: 50,
-  maxZoom: 16,
-  minPoinjavascript: 3
-});
 ```
 
-### 插件系统
+### Business features
 
 ```javascript
-// 使用内置插件
-const measurePlugin = new MeasurePlugin();
-sdk.use(measurePlugin);
-
-// 启用测量功能
-measurePlugin.enable('distance');  // 距离测量
-measurePlugin.enable('area');      // 面积测量
-measurePlugin.disable();           // 禁用测量
-
-// 获取插件
-const plugin = sdk.getPlugin<MeasurePlugin>('measure');
+sdk.notam.open(true);          // NOTAM
+sdk.adsb.open();               // ADS-B
+sdk.api.getRadarData();        // weather radar data
 ```
 
-### 错误处理
+### Popup
 
 ```javascript
-// 自定义错误处理器
-const errorHandler = (error) => {
-  console.error('Error Code:', error.code);
-  console.error('Error Details:', error.details);
-  console.error('Recoverable:', error.recoverable);
-};
-
-const sdk = new MapSDK({
-  container: 'map',
-  errorHandler
-});
-
-// 获取错误统计
-const errorStajavascript = sdk.getErrorStajavascript();
-console.log('Total Errors:', errorStajavascript.total);
+const popup = new navMap.Popup()
+  .setLngLat([lng, lat])
+  .setHTML('<h3>Title</h3>')
+  .addTo(sdk.map);
 ```
 
-### 性能监控
+### Plugins
 
 ```javascript
-// 获取性能统计
-const perfStajavascript = sdk.getPerformanceStajavascript();
-console.log('Visible Layers:', perfStajavascript.visibleLayers);
-console.log('LOD Enabled:', perfStajavascript.lodEnabled);
-console.log('Clustering Enabled:', perfStajavascript.clusteringEnabled);
-console.log('Lazy Loading Enabled:', perfStajavascript.lazyLoadingEnabled);
-```
-
-## 🔧 开发插件
-
-### 插件接口
+const measure = new navMap.MeasurePlugin();
+sdk.use(measure);
+measure.enable('distance');    // 'distance' | 'area'
+measure.disable();
 
-```javascript
-import type { IPlugin, IMapSDK } from 'maplibre-sdk';
-
-export class MyPlugin implemenjavascript IPlugin {
-  public name = 'my-plugin';
-  public version = '1.0.0';
-  
-  install(sdk: IMapSDK): void {
-    // 插件安装逻辑
-    console.log('Plugin installed');
-  }
-  
-  uninstall(sdk: IMapSDK): void {
-    // 插件卸载逻辑
-    console.log('Plugin uninstalled');
-  }
-}
+const plugin = sdk.getPlugin('measure');
 ```
 
-### 使用插件
+### Underlying engine passthrough
 
-```javascript
-import { MyPlugin } from './MyPlugin';
+The SDK passes through the full underlying map-engine API — call methods directly on the instance, or access the raw instance via `sdk.map`:
 
-const plugin = new MyPlugin();
-sdk.use(plugin);
+```javascript
+sdk.flyTo({ center: [lng, lat], zoom: 8 });
+sdk.setPaintProperty('airline', 'line-color', '#0057c8');
+sdk.queryRenderedFeatures([x, y]);
 
-// 检查插件状态
-const hasPlugin = sdk.pluginManager.hasPlugin('my-plugin');
-const pluginStajavascript = sdk.pluginManager.getPluginStajavascript();
+const map = sdk.map;  // raw map instance
 ```
 
-## 🏗️ 构建与开发
-
-```bash
-# 安装依赖
-pnpm install
-
-# 开发模式构建
-pnpm build:dev
-
-# 生产模式构建
-pnpm build:prod
+### Error & performance
 
-# 类型检查
-pnpm type-check
+```javascript
+const sdk = new navMap.MapSDK({
+  container: 'map',
+  errorHandler: (error) => console.error(error.code, error.details),
+});
 
-# 清理构建产物
-pnpm clean
+sdk.getErrorStats();        // error statistics
+sdk.getPerformanceStats();  // performance statistics
 ```
 
-## 📊 性能特性
-
-### LOD (Level of Detail)
-- 根据缩放级别自动调整图层细节
-- 低缩放级别使用简化样式
-- 高缩放级别显示完整细节
-
-### 懒加载
-- 图层按需加载，提升初始化速度
-- 支持图层加载优先级设置
-- 智能的加载队列管理
-
-### 聚类
-- 大数据量点的智能聚合
-- 可配置的聚类参数
-- 平滑的聚合动画效果
+## 🔧 Writing a Plugin
 
-## 🛡️ 错误处理特性
-
-### 错误分类
-- **可恢复错误**: 系统自动处理，不影响主要功能
-- **不可恢复错误**: 需要用户干预或系统重启
-
-### 错误统计
-- 错误历史记录
-- 错误类型分析
-- 错误趋势监控
-
-### 降级策略
-- 功能降级处理
-- 备用方案切换
-- 用户友好的错误提示
-
-## 📁 项目结构
+```javascript
+export class MyPlugin {
+  name = 'my-plugin';
+  version = '1.0.0';
+  install(sdk) { /* install logic */ }
+  uninstall(sdk) { /* uninstall logic */ }
+}
 
-```
-src/
-├── managers/           # 管理器模块
-│   ├── LayerManager.javascript      # 图层管理
-│   ├── GeoJSONManager.javascript    # GeoJSON管理
-│   ├── ErrorManager.javascript      # 错误管理
-│   ├── PerformanceManager.javascript # 性能管理
-│   └── PluginManager.javascript     # 插件管理
-├── plugins/            # 插件模块
-│   └── MeasurePlugin.javascript     # 测量插件示例
-├── types/              # 类型定义
-├── constanjavascript/          # 常量定义
-├── MapSDK.javascript          # 主SDK类
-└── index.javascript           # 导出文件
+const plugin = new MyPlugin();
+sdk.use(plugin);
+sdk.pluginManager.hasPlugin('my-plugin');
 ```
 
-## 🔮 未来规划
-
-- [ ] 更多内置插件（编辑工具、分析工具等）
-- [ ] 高级性能优化（WebGL优化、内存管理）
-- [ ] 更多数据源支持（WMS、WFS、3D Tiles等）
-- [ ] 移动端优化
-- [ ] 国际化支持
-
-## 📄 许可证
+## 📄 License
 
 MIT License
- 
-
-## 开发规范
--   [代码规范](docs/code-specification.md)
--   [JSDoc注释规范](docs/jsdoc-specification.md)
--   [发版说明](docs/release-notes-specification.md)