@lumikmz/kmz 0.2.1 → 0.4.0

package/README.md

@@ -38,12 +38,12 @@ Compile a `Template` into the executable `Waylines` shape that DJI's flight cont
 
 Dispatch is by `template.Folder.templateType`:
 
-| templateType    | Algorithm                                                                          |
-| --------------- | ---------------------------------------------------------------------------------- |
-| `waypoint`      | One Folder. Each template Placemark → one wayline Placemark, resolving `useGlobalXxx` flags against folder defaults. |
-| `mapping2d`     | One Folder. Boustrophedon (serpentine) scan over the Polygon at `folder.height`, line spacing computed from `overlap.orthoCameraOverlapW`. Per-segment `takePhoto` between adjacent points. |
-| `mapping3d`     | **Five Folders** — one nadir ortho pass + four oblique passes (front/back/left/right) at `inclinedGimbalPitch`. Photos timed via `multipleTiming` trigger. |
-| `mappingStrip`  | One Folder. LineString vertices become waypoints; if `stripUseTemplateAltitude` is true, per-vertex altitude is read from the LineString triples, otherwise folder `height` is used. |
+| templateType   | Algorithm                                                                                                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `waypoint`     | One Folder. Each template Placemark → one wayline Placemark, resolving `useGlobalXxx` flags against folder defaults.                                                                        |
+| `mapping2d`    | One Folder. Boustrophedon (serpentine) scan over the Polygon at `folder.height`, line spacing computed from `overlap.orthoCameraOverlapW`. Per-segment `takePhoto` between adjacent points. |
+| `mapping3d`    | **Five Folders** — one nadir ortho pass + four oblique passes (front/back/left/right) at `inclinedGimbalPitch`. Photos timed via `multipleTiming` trigger.                                  |
+| `mappingStrip` | One Folder. LineString vertices become waypoints; if `stripUseTemplateAltitude` is true, per-vertex altitude is read from the LineString triples, otherwise folder `height` is used.        |
 
 ```ts
 import { plan } from "@lumikmz/kmz";
@@ -74,7 +74,7 @@ Checks performed:
 
 ```ts
 interface Issue {
-  path: string;          // dot-path to the offending field, e.g. "Folder.Placemark[2].waypointSpeed"
+  path: string; // dot-path to the offending field, e.g. "Folder.Placemark[2].waypointSpeed"
   message: string;
   severity: "error" | "warning";
 }
@@ -85,16 +85,12 @@ interface Issue {
 ### Document roots: `Template` & `Waylines`
 
 ```ts
-type Template =
-  | WaypointTemplate
-  | Mapping2dTemplate
-  | Mapping3dTemplate
-  | MappingStripTemplate;
+type Template = WaypointTemplate | Mapping2dTemplate | Mapping3dTemplate | MappingStripTemplate;
 
 interface TemplateDocumentBase {
   author?: string;
-  createTime?: number;      // Unix ms
-  updateTime?: number;      // Unix ms
+  createTime?: number; // Unix ms
+  updateTime?: number; // Unix ms
   missionConfig: MissionConfig;
   // Folder is added per variant
 }
@@ -123,15 +119,15 @@ interface MissionConfig {
   flyToWaylineMode: "safely" | "pointToPoint";
   finishAction: "goHome" | "noAction" | "autoLand" | "gotoFirstWaypoint";
   exitOnRCLost: "goContinue" | "executeLostAction";
-  executeRCLostAction?: "goBack" | "landing" | "hover";  // required iff exitOnRCLost === "executeLostAction"
+  executeRCLostAction?: "goBack" | "landing" | "hover"; // required iff exitOnRCLost === "executeLostAction"
   takeOffSecurityHeight: Meters;
   takeOffRefPoint?: LngLatHeight;
   takeOffRefPointAGLHeight?: Meters;
-  globalTransitionalSpeed: MetersPerSecond;              // [1, 15]
-  globalRTHHeight: Meters;                               // [2, 1500]
+  globalTransitionalSpeed: MetersPerSecond; // [1, 15]
+  globalRTHHeight: Meters; // [2, 1500]
   droneInfo: DroneInfo;
   payloadInfo: PayloadInfo[];
-  autoRerouteInfo?: AutoRerouteInfo;                     // M3D/M3TD, M4D/M4TD, M4E/M4T only
+  autoRerouteInfo?: AutoRerouteInfo; // M3D/M3TD, M4D/M4TD, M4E/M4T only
 }
 
 interface DroneInfo {
@@ -165,9 +161,9 @@ interface WaypointFolder {
   payloadParam?: PayloadParam;
 
   globalWaypointTurnMode: WaypointTurnMode;
-  globalUseStraightLine?: boolean;        // required iff turnMode ∈ {ContinuityCurvature variants}
+  globalUseStraightLine?: boolean; // required iff turnMode ∈ {ContinuityCurvature variants}
   gimbalPitchMode: "manual" | "usePointSetting";
-  globalHeight: Meters;                   // relative to takeoff point
+  globalHeight: Meters; // relative to takeoff point
   globalWaypointHeadingParam: WaypointHeadingParam;
 
   Placemark: TemplateWaypointPlacemark[];
@@ -184,23 +180,23 @@ interface Mapping2dFolder {
   autoFlightSpeed: MetersPerSecond;
   payloadParam?: PayloadParam;
 
-  caliFlightEnable?: boolean;             // M300/M350 only
+  caliFlightEnable?: boolean; // M300/M350 only
   elevationOptimizeEnable: boolean;
-  smartObliqueEnable?: boolean;           // turns "ortho" into "smart oblique"
+  smartObliqueEnable?: boolean; // turns "ortho" into "smart oblique"
   smartObliqueGimbalPitch?: Degrees;
 
   shootType: "time" | "distance";
-  direction: Degrees;                     // [0, 360]
+  direction: Degrees; // [0, 360]
   margin: number;
   overlap: Overlap;
   ellipsoidHeight: Meters;
   height: Meters;
 
-  facadeWaylineEnable?: boolean;          // M3E/M3T/M3M only
+  facadeWaylineEnable?: boolean; // M3E/M3T/M3M only
   mappingHeadingParam?: MappingHeadingParam;
   gimbalPitchMode?: "manual" | "fixed";
-  gimbalPitchAngle?: Degrees;             // required iff gimbalPitchMode === "fixed"
-  quickOrthoMappingEnable?: boolean;      // M4E only
+  gimbalPitchAngle?: Degrees; // required iff gimbalPitchMode === "fixed"
+  quickOrthoMappingEnable?: boolean; // M4E only
   quickOrthoMappingPitch?: Degrees;
 
   Placemark: TemplatePolygonPlacemark;
@@ -218,8 +214,8 @@ interface Mapping3dFolder {
   payloadParam?: PayloadParam;
 
   caliFlightEnable?: boolean;
-  inclinedGimbalPitch: Degrees;           // pitch for the 4 oblique passes
-  inclinedFlightSpeed: MetersPerSecond;   // [1, 15]
+  inclinedGimbalPitch: Degrees; // pitch for the 4 oblique passes
+  inclinedFlightSpeed: MetersPerSecond; // [1, 15]
   shootType: "time" | "distance";
   direction: Degrees;
   margin: number;
@@ -244,7 +240,7 @@ interface MappingStripFolder {
   caliFlightEnable: boolean;
   shootType: "time" | "distance";
   direction: Degrees;
-  margin: number;                         // float (vs integer in mapping2d/3d)
+  margin: number; // float (vs integer in mapping2d/3d)
   singleLineEnable: boolean;
   cuttingDistance: number;
   boundaryOptimEnable: boolean;
@@ -254,7 +250,7 @@ interface MappingStripFolder {
   overlap: Overlap;
   ellipsoidHeight: Meters;
   height: Meters;
-  stripUseTemplateAltitude: boolean;      // when true, alt is read from LineString triples
+  stripUseTemplateAltitude: boolean; // when true, alt is read from LineString triples
 
   Placemark: TemplateLineStringPlacemark;
 }
@@ -268,15 +264,15 @@ Two Placemark shapes — one for `template.kml`, one for `waylines.wpml`.
 
 ```ts
 interface TemplateWaypointPlacemark {
-  Point: { coordinates: LngLat };          // KML order: lng,lat
+  Point: { coordinates: LngLat }; // KML order: lng,lat
   index: number;
 
   useGlobalHeight: boolean;
-  ellipsoidHeight?: Meters;                // required iff useGlobalHeight=false; WGS84
-  height?: Meters;                         // required iff useGlobalHeight=false
+  ellipsoidHeight?: Meters; // required iff useGlobalHeight=false; WGS84
+  height?: Meters; // required iff useGlobalHeight=false
 
   useGlobalSpeed: boolean;
-  waypointSpeed?: MetersPerSecond;         // required iff useGlobalSpeed=false; [1, 15]
+  waypointSpeed?: MetersPerSecond; // required iff useGlobalSpeed=false; [1, 15]
 
   useGlobalHeadingParam: boolean;
   waypointHeadingParam?: WaypointHeadingParam;
@@ -284,9 +280,9 @@ interface TemplateWaypointPlacemark {
   useGlobalTurnParam: boolean;
   waypointTurnParam?: WaypointTurnParam;
 
-  useStraightLine?: boolean;               // required for certain turn modes
-  gimbalPitchAngle?: Degrees;              // required iff folder gimbalPitchMode === "usePointSetting"
-  isRisky?: boolean;                       // M30/M30T, M3D/M3TD, M4D/M4TD, M4E/M4T
+  useStraightLine?: boolean; // required for certain turn modes
+  gimbalPitchAngle?: Degrees; // required iff folder gimbalPitchMode === "usePointSetting"
+  isRisky?: boolean; // M30/M30T, M3D/M3TD, M4D/M4TD, M4E/M4T
 
   actionGroup?: ActionGroup[];
 }
@@ -300,7 +296,7 @@ interface TemplatePolygonPlacemark {
 }
 
 interface TemplateLineStringPlacemark {
-  LineString: { coordinates: string };     // space-separated lng,lat,alt triples
+  LineString: { coordinates: string }; // space-separated lng,lat,alt triples
 }
 ```
 
@@ -312,8 +308,8 @@ The `useGlobalXxx` switches are template-only — in `waylines.wpml` all params
 interface WaylinesPlacemark {
   Point: { coordinates: LngLat };
   index: number;
-  executeHeight: Meters;                   // interpreted per Folder.executeHeightMode
-  waypointSpeed: MetersPerSecond;          // [1, 15]
+  executeHeight: Meters; // interpreted per Folder.executeHeightMode
+  waypointSpeed: MetersPerSecond; // [1, 15]
   waypointHeadingParam: WaypointHeadingParam;
   waypointTurnParam: WaypointTurnParam;
   useStraightLine?: boolean;
@@ -327,9 +323,9 @@ interface WaylinesPlacemark {
 ```ts
 interface WaypointHeadingParam {
   waypointHeadingMode: "followWayline" | "manually" | "fixed" | "smoothTransition" | "towardPOI";
-  waypointHeadingAngle?: Degrees;          // [-180, 180]; required iff mode === "smoothTransition"
-  waypointPoiPoint?: LngLatHeight;         // required iff mode === "towardPOI"; height should be 0
-  waypointHeadingPathMode: "clockwise" | "counterClockwise" | "followBadArc";  // spec typo preserved
+  waypointHeadingAngle?: Degrees; // [-180, 180]; required iff mode === "smoothTransition"
+  waypointPoiPoint?: LngLatHeight; // required iff mode === "towardPOI"; height should be 0
+  waypointHeadingPathMode: "clockwise" | "counterClockwise" | "followBadArc"; // spec typo preserved
 }
 
 interface WaypointTurnParam {
@@ -338,27 +334,27 @@ interface WaypointTurnParam {
     | "toPointAndStopWithDiscontinuityCurvature"
     | "toPointAndStopWithContinuityCurvature"
     | "toPointAndPassWithContinuityCurvature";
-  waypointTurnDampingDist?: Meters;        // required for coordinateTurn or pass+useStraightLine
+  waypointTurnDampingDist?: Meters; // required for coordinateTurn or pass+useStraightLine
 }
 
 interface WaylineCoordinateSysParam {
-  coordinateMode: "WGS84";                 // only value currently
+  coordinateMode: "WGS84"; // only value currently
   heightMode: "EGM96" | "relativeToStartPoint" | "aboveGroundLevel" | "realTimeFollowSurface";
   positioningType?: "GPS" | "RTKBaseStation" | "QianXun" | "Custom";
-  globalShootHeight?: Meters;              // mapping templates
-  surfaceFollowModeEnable?: boolean;       // mapping templates
-  surfaceRelativeHeight?: Meters;          // required iff surfaceFollowModeEnable === true
+  globalShootHeight?: Meters; // mapping templates
+  surfaceFollowModeEnable?: boolean; // mapping templates
+  surfaceRelativeHeight?: Meters; // required iff surfaceFollowModeEnable === true
 }
 
 interface MappingHeadingParam {
   mappingHeadingMode: "fixed" | "followWayline";
-  mappingHeadingAngle?: Degrees;           // [0, 360]; required iff mode === "fixed"
+  mappingHeadingAngle?: Degrees; // [0, 360]; required iff mode === "fixed"
 }
 
 interface Overlap {
-  orthoLidarOverlapH?: number;             // 0–100, M300/M350 LiDAR
+  orthoLidarOverlapH?: number; // 0–100, M300/M350 LiDAR
   orthoLidarOverlapW?: number;
-  orthoCameraOverlapH?: number;            // 0–100, visible light
+  orthoCameraOverlapH?: number; // 0–100, visible light
   orthoCameraOverlapW?: number;
   inclinedLidarOverlapH?: number;
   inclinedLidarOverlapW?: number;
@@ -375,15 +371,15 @@ interface Overlap {
 interface ActionGroup {
   actionGroupId: number;
   actionGroupStartIndex: number;
-  actionGroupEndIndex: number;             // ≥ start; equal means single-waypoint group
-  actionGroupMode: "sequence";             // only value currently
+  actionGroupEndIndex: number; // ≥ start; equal means single-waypoint group
+  actionGroupMode: "sequence"; // only value currently
   actionTrigger: ActionTrigger;
-  action: Action[];                        // 1..*
+  action: Action[]; // 1..*
 }
 
 interface ActionTrigger {
   actionTriggerType: "reachPoint" | "betweenAdjacentPoints" | "multipleTiming" | "multipleDistance";
-  actionTriggerParam?: number;             // seconds for multipleTiming; meters for multipleDistance
+  actionTriggerParam?: number; // seconds for multipleTiming; meters for multipleDistance
 }
 
 type Action =
@@ -411,7 +407,7 @@ Every `Action` has the shape:
 interface ActionBase<F extends string, P> {
   actionId: number;
   actionActuatorFunc: F;
-  actionActuatorFuncParam: P;              // shape depends on F
+  actionActuatorFuncParam: P; // shape depends on F
 }
 ```
 
@@ -421,7 +417,7 @@ The 16 param shapes match [`docs/kmz/common-element.html` §action](../../docs/k
 interface TakePhotoParam {
   payloadPositionIndex: number;
   fileSuffix?: string;
-  payloadLensIndex?: LensType[];           // ["wide", "ir", ...]
+  payloadLensIndex?: LensType[]; // ["wide", "ir", ...]
   useGlobalPayloadLensIndex: boolean;
 }
 
@@ -436,11 +432,11 @@ interface GimbalRotateParam {
   gimbalYawRotateEnable: boolean;
   gimbalYawRotateAngle: Degrees;
   gimbalRotateTimeEnable: boolean;
-  gimbalRotateTime: number;                // seconds
+  gimbalRotateTime: number; // seconds
 }
 
 interface HoverParam {
-  hoverTime: number;                       // seconds, > 0
+  hoverTime: number; // seconds, > 0
 }
 ```
 
@@ -451,18 +447,25 @@ For the full list — including `accurateShoot` (deprecated, prefer `orientedSho
 Nominal types to prevent unit mix-ups. They are plain numbers at runtime.
 
 ```ts
-type Meters          = number & { readonly __brand: "Meters" };
+type Meters = number & { readonly __brand: "Meters" };
 type MetersPerSecond = number & { readonly __brand: "MetersPerSecond" };
-type Degrees         = number & { readonly __brand: "Degrees" };
+type Degrees = number & { readonly __brand: "Degrees" };
 
 // Constructors (no-op at runtime)
-const meters          = (n: number): Meters          => n as Meters;
+const meters = (n: number): Meters => n as Meters;
 const metersPerSecond = (n: number): MetersPerSecond => n as MetersPerSecond;
-const degrees         = (n: number): Degrees         => n as Degrees;
+const degrees = (n: number): Degrees => n as Degrees;
 
 // Geographic types
-interface LngLat       { lng: number; lat: number; }
-interface LngLatHeight { lng: number; lat: number; height: Meters; }
+interface LngLat {
+  lng: number;
+  lat: number;
+}
+interface LngLatHeight {
+  lng: number;
+  lat: number;
+  height: Meters;
+}
 ```
 
 ### Enums
@@ -533,7 +536,7 @@ Output is always a single `Waylines` object containing `1..n` `Folder` entries.
 
 ## Compatibility
 
-[DJI WPML 1.0.2](https://developer.dji.com/doc/cloud-api-tutorial/en/feature-set/dji-wpml/template-kml.html) — see [`docs/kmz-types-spec.md`](../../docs/kmz-types-spec.md) for the distilled spec this package mirrors.
+[DJI WPML 1.15](https://developer.dji.com/doc/cloud-api-tutorial/cn/api-reference/dji-wpml/overview.html) — see [`docs/kmz-types-spec.md`](../../docs/kmz-types-spec.md) for the distilled spec this package mirrors.
 
 ## License