drone-camera 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chenlong2019
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# drone-camera
+
+**A framework-agnostic drone control library for the browser — one flight core, two renderers (three.js & CesiumJS).**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/chenlong2019/drone-camera/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)](./tsconfig.lib.json)
+![three.js](https://img.shields.io/badge/three.js-%3E%3D0.180-black)
+![CesiumJS](https://img.shields.io/badge/CesiumJS-compatible-6CADDF)
+
+[中文文档](https://github.com/chenlong2019/drone-camera/blob/main/README.zh-CN.md)
+
+</div>
+
+<table>
+<tr>
+<td width="50%"><img src="https://cdn.jsdelivr.net/gh/chenlong2019/drone-camera@main/docs/images/three-follow.jpg" alt="three.js backend: follow camera, flight panel, mini-map" /></td>
+<td width="50%"><img src="https://cdn.jsdelivr.net/gh/chenlong2019/drone-camera@main/docs/images/cesium-mission.jpg" alt="Cesium backend: real-Earth mission editing over satellite imagery" /></td>
+</tr>
+<tr>
+<td align="center"><sub><b>three.js</b> — follow camera, flight panel, mini-map (local sandbox)</sub></td>
+<td align="center"><sub><b>CesiumJS</b> — real-Earth coordinates (ENU/ECEF), in-scene waypoint editing</sub></td>
+</tr>
+</table>
+
+## Why
+
+Browser drone simulators exist. GIS drones on a 3D globe exist. **One flight core driving both — with a complete camera-to-panorama pipeline — does not.** drone-camera fills that gap:
+
+- **One core, two renderers** — the same `DroneSim` flight-state machine (physics, battery, failsafes, geofence, obstacle AABB) drives a three.js WebGPU sandbox *and* a CesiumJS real-Earth backend. Switch backends with a single option; panels, mission editor and mini-map don't change.
+- **Zero-dependency core** — `drone-sim` runs in Node or a Web Worker with no DOM, no three, no browser. Test your flight logic headlessly.
+- **Complete imaging pipeline** — photo/video capture with camera intrinsics, automated panorama flights (wide / 180° / full 360°), pose-based stitching (no feature matching, no OpenCV), an equirectangular viewer, and a capture gallery with EXIF/GPS import for real photos.
+- **AI-ready** — an MCP server exposes 14 `drone_*` tools so an AI agent can fly the drone, edit missions, and take photos. Headless driver included.
+- **Framework-free UI** — panels are plain DOM (Vue/React/svelte/no-framework, all fine). The library itself imports nothing from any UI framework.
+
+## Install
+
+```sh
+npm install drone-camera three
+# TypeScript users:
+npm install -D @types/three
+```
+
+> three.js is a **peer dependency** and stays external in ESM builds, so you never get two copies of three on one page. A UMD build with three bundled is also included (`index.umd.cjs`, exposes `window.DroneControl`).
+
+## Quick start (three.js)
+
+```ts
+import * as THREE from 'three'
+import { WebGPURenderer } from 'three/webgpu'
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
+import { createDroneControl, DroneControlPanel } from 'drone-camera'
+
+const scene = new THREE.Scene()
+const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, 0.1, 4000)
+const renderer = new WebGPURenderer({ antialias: true })
+renderer.setSize(innerWidth, innerHeight)
+document.body.appendChild(renderer.domElement)
+const controls = new OrbitControls(camera, renderer.domElement)
+
+// Assembles physics core + vehicle rig + gimbal + night LED lights + ranging radar.
+// No modelUrl → built-in procedural quadcopter (zero assets required).
+const drone = await createDroneControl({ engine: 'three', scene, camera, renderer, controls })
+
+// Native DOM panel: arm/takeoff/land, sticks, flight modes, camera views, photo & video.
+new DroneControlPanel(drone)
+
+renderer.setAnimationLoop(() => {
+  drone.animate()
+  if (drone.isOrbitView) controls.update()
+  drone.captureRecordingFrame()   // gimbal framing for photo/video, no-op otherwise
+  drone.onBeforeRender()
+  renderer.render(scene, camera)
+  drone.onAfterRender()
+})
+```
+
+Orbit around it, switch to FPV, gimbal it, take a photo — all from the panel. Keyboard flight is built in.
+
+## Switch to CesiumJS (same code, real Earth)
+
+```ts
+import { createDroneControl, loadCesiumScript } from 'drone-camera'
+
+await loadCesiumScript('/Cesium/Cesium.js')
+
+// ENU/ECEF earth coordinates; origin altitude auto-sampled from terrain
+const drone = await createDroneControl({ engine: 'cesium', viewer, lon: 116.391, lat: 39.906 })
+
+// Same panels — new DroneControlPanel(drone) works unchanged.
+```
+
+## Features
+
+| | |
+|---|---|
+| ✈️ Flight core | State machine (disarmed → armed → takeoff → flight → RTH → land), battery model, failsafes, altitude/distance ceilings, obstacle AABB avoidance, event log |
+| 🎮 Control | Stick normalization, keyboard control, motion/normal modes, speed & attitude limits |
+| 🛰 Backends | `three` (WebGPU sandbox) and `cesium` (real Earth) behind one interface — `createDroneControl({ engine })` |
+| 🧊 Vehicle | Procedural built-in quadcopter or any GLB; arms/props/gimbal driven by semantic node names; night LED lights; ranging radar |
+| 📷 Capture | Photo & video with camera pose + intrinsics, gimbal framing, capture sessions |
+| 🌏 Panorama | Auto flight patterns (wide 9-shot / 180° 21-shot / 360°), pose-based stitching to equirectangular, spherical WebGL viewer |
+| 🗺 Missions | In-scene waypoint editing (drag / Shift-altitude / insert / delete), execution, JSON/CSV/Manifest export |
+| 🖥 UI | Plain-DOM flight panel, mission panel, capture panel, mini-map, gallery popups — mount anywhere |
+| 🤖 AI | MCP server with 14 tools + headless CLI driver for scripted/agent flights |
+
+## Panorama in three lines
+
+```ts
+import { CaptureService, PanoramaCapture } from 'drone-camera'
+
+const capture = new CaptureService({ provider: drone })   // drone = your engine host
+const session = capture.createSession({ source: 'virtual-camera', name: 'Around the tower' })
+const pano = new PanoramaCapture(capture)
+await pano.start(session.id, 'pano-360')   // body spins for yaw, gimbal stacks pitch rows
+```
+
+Stitching exploits the fact that every shot's camera pose is known exactly — images are back-projected onto the equirectangular canvas, no feature matching or OpenCV involved.
+
+## Documentation
+
+Full API reference, generated from the library's own `.d.ts`:
+
+- `docs/` route in the demo app — usage guide
+- `api-docs/` route — **1088 documented members** across 24 modules
+- `class-map/` route — interactive architecture map (Vue Flow)
+
+## Demo
+
+```sh
+npm install
+npm run dev          # → /three-demo  /cesium-demo  /docs  /api-docs
+```
+
+## AI agent mode (MCP)
+
+The repo ships `mcp/drone-mcp-server.mjs` — a stdio MCP server exposing the running demo to an AI agent: take off, fly waypoints, edit missions, gimbal, shoot panoramas, read radar, screenshot. Wire it into any MCP client and let the model fly.
+
+## Architecture
+
+```
+┌───────────────────────── UI (plain DOM, framework-free) ─────────────────────────┐
+│   DroneControlPanel  MissionPanel      CapturePanel       MiniMap   Gallery   │
+└──────────────────────────────────────┬───────────────────────────────────────────┘
+                                       │ host interfaces (not inheritance)
+┌──────────────────────────────────────┴───────────────────────────────────────────┐
+│              createDroneControl({ engine: 'three' | 'cesium' })                   │
+├──────────────────────────────┬────────────────────────────────────────────────────┤
+│  DroneFly (three.js/WebGPU)  │  CesiumDroneAdapter (ENU/ECEF real Earth)           │
+├──────────────────────────────┴────────────────────────────────────────────────────┤
+│  DroneSim — zero-dependency flight core (Node / Worker / browser)                 │
+└───────────────────────────────────────────────────────────────────────────────────┘
+```
+
+## License
+
+[MIT](https://github.com/chenlong2019/drone-camera/blob/main/LICENSE)

package/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 无人机控制系统（Drone Control System）—— 独立 npm 库 / ES6 模块统一入口。
+ *
+ * 迁移自 first-app 的 src/lib/three-engine，仅取「飞控」相关模块，
+ * 不含模型查看器、模型体检、批处理、赛道等其它模块。
+ *
+ * 设计约定：
+ * - 本入口只做「再导出」，不含任何业务装配逻辑，也不引用 Vue —— 整个 src/lib 与框架无关；
+ * - `three` 系列模块在 ESM 库构建里全部 external（作为 peerDependency，由使用方提供实例），
+ *   避免同一页面出现两份 three 实例（WebGPURenderer 与 TSL 节点会因此彻底失效）；
+ * - 真正零依赖的只有 `./drone-camera/drone-sim`，可单独在 Node / Web Worker 中运行。
+ *
+ * 渲染后端（两套实现同一个 DronePanelHost 接口，由 `createDroneControl({ engine })` 装配）：
+ * - `engine: 'three'`  —— DroneFly：three.js + WebGPURenderer 飞行沙盒（缺省）
+ * - `engine: 'cesium'` —— CesiumDroneAdapter：地球坐标系（ENU/ECEF）下的飞行
+ * 飞行内核都是同一个 DroneSim；控制面板 / 航线面板 / 鹰眼图 / 键盘控制完全不区分后端。
+ *
+ * 运行期资产（非构建依赖，由使用方自行提供）：
+ * - `drone-fly.initialize()` 不传 `modelUrl` 时用**内置积木机体**（程序化几何体拼的四轴，
+ *   零资产依赖，节点命名与真机 ID 表一致，机臂/桨叶/云台/灯光/雷达全部可用）；
+ * - 要真机模型就显式传路径：`.initialize({ modelUrl: DRONE_MODEL_URL })`（默认指向
+ *   `/models/djiair_renamed.glb`）或任意自己的 `.glb`。
+ */
+export * from './lib/drone-sim';
+export * from './lib/drone-control';
+export * from './lib/drone-world';
+export * from './lib/drone-rig';
+export * from './lib/drone-lights';
+export * from './lib/drone-radar';
+export * from './lib/mission-editor';
+export * from './lib/drone-fly';
+export * from './lib/drone-cesium-rig';
+export * from './lib/drone-cesium-mission';
+export * from './lib/drone-cesium';
+export * from './lib/drone-engine';
+export * from './lib/drone-panel';
+export * from './lib/mission-panel';
+export * from './lib/drone-minimap';
+export * from './lib/drone-exif';
+export * from './lib/drone-capture';
+export * from './lib/drone-capture-manifest';
+export * from './lib/drone-capture-panel';
+export * from './lib/drone-gallery';
+export * from './lib/drone-image-utils';
+export * from './lib/drone-image-viewer';
+export * from './lib/drone-panorama-viewer';
+export * from './lib/drone-panorama';
+export * from './lib/drone-stitch';
+export * from './lib/drone-photogrammetry';
+export * from './lib/drone-reconstruction-preview';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,cAAc,0BAA0B,CAAA;AAKxC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,0BAA0B,CAAA;AACxC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,+BAA+B,CAAA;AAM7C,cAAc,0BAA0B,CAAA;AAexC,cAAc,iCAAiC,CAAA;AAC/C,cAAc,qCAAqC,CAAA;AACnD,cAAc,6BAA6B,CAAA;AAO3C,cAAc,6BAA6B,CAAA;AAM3C,cAAc,4BAA4B,CAAA;AAM1C,cAAc,8BAA8B,CAAA;AAO5C,cAAc,8BAA8B,CAAA;AAwB5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,uCAAuC,CAAA;AACrD,cAAc,oCAAoC,CAAA;AAClD,cAAc,8BAA8B,CAAA;AAC5C,cAAc,kCAAkC,CAAA;AAChD,cAAc,mCAAmC,CAAA;AACjD,cAAc,sCAAsC,CAAA;AACpD,cAAc,+BAA+B,CAAA;AAC7C,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qCAAqC,CAAA;AACnD,cAAc,6CAA6C,CAAA"}