@lumikmz/kmz 0.2.1 → 0.4.0

package/src/types/action.ts

@@ -49,7 +49,14 @@ export type Action =
   | PanoShotAction
   | RecordPointCloudAction
   | MegaphoneAction
-  | SearchlightAction;
+  | SearchlightAction
+  | StartSmartObliqueAction
+  | StopSmartObliqueAction
+  | StartTimeLapseAction
+  | StopTimeLapseAction
+  | GimbalAngleLockAction
+  | GimbalAngleUnlockAction
+  | SetFocusTypeAction;
 
 interface ActionBase<F extends string, P> {
   actionId: number;
@@ -92,6 +99,8 @@ export interface FocusParam {
   focusRegionHeight?: number;
   /** Required on M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T. */
   isInfiniteFocus?: boolean;
+  /** Calibration focus flag, observed in mapping WPML exports. */
+  isCalibrationFocus?: boolean;
 }
 export type FocusAction = ActionBase<"focus", FocusParam>;
 
@@ -212,6 +221,8 @@ export interface PanoShotParam {
   payloadPositionIndex?: number;
   payloadLensIndex?: LensType[];
   useGlobalPayloadLensIndex?: boolean;
+  /** Photo meta tag written alongside the panorama; UUID string. */
+  actionUUID?: string;
   panoShotSubMode: PanoShotSubMode;
 }
 export type PanoShotAction = ActionBase<"panoShot", PanoShotParam>;
@@ -241,6 +252,59 @@ export interface MegaphoneParam {
 }
 export type MegaphoneAction = ActionBase<"megaphone", MegaphoneParam>;
 
+/** M4D/M4TD only — starts gimbal swing in smart-oblique mode. */
+export interface StartSmartObliqueParam {
+  payloadPositionIndex: number;
+}
+export type StartSmartObliqueAction = ActionBase<"startSmartOblique", StartSmartObliqueParam>;
+
+/** M4D/M4TD only — stops gimbal swing in smart-oblique mode. */
+export interface StopSmartObliqueParam {
+  payloadPositionIndex: number;
+}
+export type StopSmartObliqueAction = ActionBase<"stopSmartOblique", StopSmartObliqueParam>;
+
+/** Starts interval (time-lapse) shooting for a mapping strip. */
+export interface StartTimeLapseParam {
+  payloadPositionIndex: number;
+  useGlobalPayloadLensIndex: boolean;
+  /** Single lens token (not a list — mapping strips use one lens). */
+  payloadLensIndex: LensType;
+  /** Minimum shoot interval in seconds. Derived from `forwardGroundSpacing / speed`. */
+  minShootInterval: number;
+}
+export type StartTimeLapseAction = ActionBase<"startTimeLapse", StartTimeLapseParam>;
+
+/** Stops interval shooting for a mapping strip. */
+export interface StopTimeLapseParam {
+  payloadPositionIndex: number;
+  payloadLensIndex: LensType;
+}
+export type StopTimeLapseAction = ActionBase<"stopTimeLapse", StopTimeLapseParam>;
+
+/** Locks gimbal pitch angle during a mapping strip. */
+export interface GimbalAngleLockParam {
+  payloadPositionIndex: number;
+}
+export type GimbalAngleLockAction = ActionBase<"gimbalAngleLock", GimbalAngleLockParam>;
+
+/**
+ * Unlocks gimbal angle after a mapping strip ends.
+ * ⚠️ No `actionActuatorFuncParam` element is emitted in XML — this action has no params.
+ */
+export interface GimbalAngleUnlockAction {
+  actionId: number;
+  actionActuatorFunc: "gimbalAngleUnlock";
+}
+
+/** Sets camera focus mode (e.g. "manual") before a mapping run. */
+export interface SetFocusTypeParam {
+  payloadPositionIndex: number;
+  /** e.g. `"manual"`, `"auto"`. */
+  cameraFocusType: string;
+}
+export type SetFocusTypeAction = ActionBase<"setFocusType", SetFocusTypeParam>;
+
 /** M4D/M4TD only. */
 export interface SearchlightParam {
   payloadPositionIndex: number;

package/src/types/drone-payload.ts

@@ -8,6 +8,12 @@ export interface DroneInfo {
 
 export interface PayloadInfo {
   payloadEnumValue: number;
+  /**
+   * Payload sub-type (`type-subtype-gimbalindex`, the middle field). Non-standard
+   * WPML extension that DJI tooling emits; written when present. Main-gimbal
+   * cameras are subtype 0 (e.g. M4TD Camera = 99-0-0).
+   */
+  payloadSubEnumValue?: number;
   payloadPositionIndex: number;
 }
 
@@ -31,18 +37,18 @@ export const DroneEnum = {
 
 /** Payload `{ payloadEnumValue, payloadPositionIndex }` tuples for common cameras. */
 export const PayloadEnum = {
-  // Main gimbal cameras
-  M30Camera: { payloadEnumValue: 52, payloadPositionIndex: 0 },
-  M30TCamera: { payloadEnumValue: 53, payloadPositionIndex: 0 },
-  M3ECamera: { payloadEnumValue: 66, payloadPositionIndex: 0 },
-  M3TCamera: { payloadEnumValue: 67, payloadPositionIndex: 0 },
-  M3TACamera: { payloadEnumValue: 129, payloadPositionIndex: 0 },
-  M3DCamera: { payloadEnumValue: 80, payloadPositionIndex: 0 },
-  M3TDCamera: { payloadEnumValue: 81, payloadPositionIndex: 0 },
-  M4DCamera: { payloadEnumValue: 98, payloadPositionIndex: 0 },
-  M4TDCamera: { payloadEnumValue: 99, payloadPositionIndex: 0 },
-  M4ECamera: { payloadEnumValue: 88, payloadPositionIndex: 0 },
-  M4TCamera: { payloadEnumValue: 89, payloadPositionIndex: 0 },
+  // Main gimbal cameras (subtype 0 = primary integrated camera)
+  M30Camera: { payloadEnumValue: 52, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M30TCamera: { payloadEnumValue: 53, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M3ECamera: { payloadEnumValue: 66, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M3TCamera: { payloadEnumValue: 67, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M3TACamera: { payloadEnumValue: 129, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M3DCamera: { payloadEnumValue: 80, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M3TDCamera: { payloadEnumValue: 81, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M4DCamera: { payloadEnumValue: 98, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M4TDCamera: { payloadEnumValue: 99, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M4ECamera: { payloadEnumValue: 88, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
+  M4TCamera: { payloadEnumValue: 89, payloadSubEnumValue: 0, payloadPositionIndex: 0 },
   // Zenmuse mounts: 0=front-left/main, 1=front-right, 2=top (M300 RTK), 0=main for others
   ZenmuseZ30: { payloadEnumValue: 20, payloadPositionIndex: 0 },
   ZenmuseXT2: { payloadEnumValue: 26, payloadPositionIndex: 0 },

package/src/types/enums.ts

@@ -82,9 +82,23 @@ export type ActionActuatorFunc =
   | "panoShot"
   | "recordPointCloud"
   | "megaphone"
-  | "searchlight";
-
-export type GimbalHeadingYawBase = "north";
+  | "searchlight"
+  /** ⚠️ NON-SPEC — observed in real DJI KMZ exports, absent from WPML 1.15 docs. */
+  | "startSmartOblique"
+  /** ⚠️ NON-SPEC — observed in real DJI KMZ exports, absent from WPML 1.15 docs. */
+  | "stopSmartOblique"
+  /** Starts time-lapse (interval) shooting for a mapping strip. */
+  | "startTimeLapse"
+  /** Stops time-lapse shooting. */
+  | "stopTimeLapse"
+  /** Locks gimbal angle during a mapping strip. */
+  | "gimbalAngleLock"
+  /** Unlocks gimbal angle (no params in XML). */
+  | "gimbalAngleUnlock"
+  /** Sets camera focus mode (manual / auto). */
+  | "setFocusType";
+
+export type GimbalHeadingYawBase = "north" | "aircraft";
 
 export type GimbalRotateMode = "absoluteAngle";
 

package/src/types/mission-config.ts

@@ -55,4 +55,9 @@ export interface PayloadParam {
   modelColoringEnable?: boolean;
   /** Comma-joined `LensType` tokens, e.g. `["wide","ir"]`. */
   imageFormat: LensType[];
+  /**
+   * ⚠️ NON-SPEC — observed in 司空2 (FlightHub 2) KMZ exports, absent from WPML 1.15.
+   * Photo size/ratio token, e.g. `"default_l"`. Pass-through for compatibility.
+   */
+  photoSize?: string;
 }

package/src/types/placemark.ts

@@ -1,7 +1,12 @@
 import type { Degrees, LngLat, Meters, MetersPerSecond } from "./branded.js";
 import type { ActionGroup } from "./action.js";
-import type { ExecuteHeightMode } from "./enums.js";
-import type { WaypointHeadingParam, WaypointTurnParam } from "./waypoint-params.js";
+import type { ExecuteHeightMode, ShootType } from "./enums.js";
+import type {
+  MappingHeadingParam,
+  Overlap,
+  WaypointHeadingParam,
+  WaypointTurnParam,
+} from "./waypoint-params.js";
 
 // ─── Template Placemark ──────────────────────────────────────────────────────
 
@@ -47,27 +52,92 @@ export interface TemplateWaypointPlacemark {
   actionGroup?: ActionGroup[];
 }
 
-/**
- * `Placemark` inside a mapping-type Folder (mapping2d / mapping3d).
- * Holds the survey polygon. Folder-level fields carry shooting params.
- */
-export interface TemplatePolygonPlacemark {
-  Polygon: {
-    outerBoundaryIs: {
-      LinearRing: {
-        /** Space-separated `lon,lat,alt` triples. */
-        coordinates: string;
-      };
+/** Survey-area boundary polygon, shared by mapping2d / mapping3d Placemarks. */
+export interface TemplatePolygon {
+  outerBoundaryIs: {
+    LinearRing: {
+      /** Space-separated `lon,lat,alt` triples. */
+      coordinates: string;
     };
   };
 }
 
-/** Placemark for `mappingStrip` Folder — uses a LineString. */
-export interface TemplateLineStringPlacemark {
+/**
+ * `Placemark` inside a `mapping2d` Folder. Per the WPML spec the shooting/mapping
+ * params live HERE alongside the polygon — NOT on the Folder.
+ */
+export interface Mapping2dPlacemark {
+  /** M300/M350 only. */
+  caliFlightEnable?: boolean;
+  elevationOptimizeEnable: boolean;
+  /** M300/M350+P1, M3E/M3T/M3M, M3D. */
+  smartObliqueEnable?: boolean;
+  smartObliqueGimbalPitch?: Degrees;
+  /** M4E only. */
+  quickOrthoMappingEnable?: boolean;
+  /** Required iff `quickOrthoMappingEnable === true`. `[10, 30]`. */
+  quickOrthoMappingPitch?: Degrees;
+  /** M3E/M3T/M3M. */
+  facadeWaylineEnable?: boolean;
+  shootType: ShootType;
+  /** `[0, 360]`. */
+  direction: Degrees;
+  /** Outward survey-area margin, meters. */
+  margin: number;
+  /** M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T. */
+  mappingHeadingParam?: MappingHeadingParam;
+  /** M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T. */
+  gimbalPitchMode?: "manual" | "fixed";
+  /** Required iff `gimbalPitchMode === "fixed"`. `[-90, -30]`. */
+  gimbalPitchAngle?: Degrees;
+  /** Overlap ratios as percentages `[0, 100]` (e.g. `80`, not `0.8`). */
+  overlap: Overlap;
+  Polygon: TemplatePolygon;
+  /** WGS84 ellipsoid. */
+  ellipsoidHeight: Meters;
+  /** Per Folder `heightMode`. */
+  height: Meters;
+}
+
+/** `Placemark` inside a `mapping3d` (oblique) Folder. Params live here, not on the Folder. */
+export interface Mapping3dPlacemark {
+  caliFlightEnable?: boolean;
+  inclinedGimbalPitch: Degrees;
+  /** Range `[1, 15]`. */
+  inclinedFlightSpeed: MetersPerSecond;
+  shootType: ShootType;
+  direction: Degrees;
+  margin: number;
+  /** Overlap ratios as percentages `[0, 100]`. */
+  overlap: Overlap;
+  Polygon: TemplatePolygon;
+  ellipsoidHeight: Meters;
+  height: Meters;
+}
+
+/** `Placemark` inside a `mappingStrip` Folder — uses a LineString; params live here. */
+export interface MappingStripPlacemark {
+  caliFlightEnable: boolean;
+  shootType: ShootType;
+  direction: Degrees;
+  /** Float meters (vs integer in mapping2d/3d). */
+  margin: number;
+  singleLineEnable: boolean;
+  cuttingDistance: number;
+  boundaryOptimEnable: boolean;
+  leftExtend: number;
+  rightExtend: number;
+  includeCenterEnable: boolean;
+  /** Overlap ratios as percentages `[0, 100]`. */
+  overlap: Overlap;
   LineString: {
     /** Space-separated `lon,lat,alt` triples. Alt consumed only when `stripUseTemplateAltitude === true`. */
     coordinates: string;
   };
+  ellipsoidHeight: Meters;
+  height: Meters;
+  /** When true, altitudes are read from LineString triples. */
+  stripUseTemplateAltitude: boolean;
 }
 
 // ─── Waylines Placemark ──────────────────────────────────────────────────────
@@ -90,6 +160,13 @@ export interface WaylinesPlacemark {
   useStraightLine?: boolean;
   isRisky?: boolean;
   actionGroup?: ActionGroup[];
+  /** Per-waypoint gimbal orientation hint observed in mapping waylines exports. */
+  waypointGimbalHeadingParam?: {
+    waypointGimbalPitchAngle: Degrees;
+    waypointGimbalYawAngle: Degrees;
+  };
+  /** Waypoint work type; 0 = normal. Observed in mapping waylines exports. */
+  waypointWorkType?: number;
 }
 
 /** Re-export for convenience; folder-level executeHeightMode lives here. */

package/src/types/template.ts

@@ -1,15 +1,11 @@
-import type { Degrees, Meters, MetersPerSecond } from "./branded.js";
+import type { Meters, MetersPerSecond } from "./branded.js";
 import type { MissionConfig, PayloadParam } from "./mission-config.js";
-import type { GimbalPitchMode, ShootType, WaypointTurnMode } from "./enums.js";
+import type { GimbalPitchMode, WaypointTurnMode } from "./enums.js";
+import type { WaylineCoordinateSysParam, WaypointHeadingParam } from "./waypoint-params.js";
 import type {
-  MappingHeadingParam,
-  Overlap,
-  WaylineCoordinateSysParam,
-  WaypointHeadingParam,
-} from "./waypoint-params.js";
-import type {
-  TemplateLineStringPlacemark,
-  TemplatePolygonPlacemark,
+  Mapping2dPlacemark,
+  Mapping3dPlacemark,
+  MappingStripPlacemark,
   TemplateWaypointPlacemark,
 } from "./placemark.js";
 
@@ -73,40 +69,8 @@ export interface Mapping2dFolder {
   waylineCoordinateSysParam: WaylineCoordinateSysParam;
   autoFlightSpeed: MetersPerSecond;
   payloadParam?: PayloadParam;
-
-  /** M300/M350 only. */
-  caliFlightEnable?: boolean;
-  elevationOptimizeEnable: boolean;
-  /** M300/M350+P1, M3E/M3T/M3M, M3D. */
-  smartObliqueEnable?: boolean;
-  smartObliqueGimbalPitch?: Degrees;
-
-  shootType: ShootType;
-  /** `[0, 360]`. */
-  direction: Degrees;
-  /** Outward survey-area margin, meters. */
-  margin: number;
-  overlap: Overlap;
-  /** WGS84 ellipsoid. */
-  ellipsoidHeight: Meters;
-  /** Per Folder `heightMode`. */
-  height: Meters;
-
-  /** M3E/M3T/M3M. */
-  facadeWaylineEnable?: boolean;
-
-  /** M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T. */
-  mappingHeadingParam?: MappingHeadingParam;
-  /** M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T. */
-  gimbalPitchMode?: "manual" | "fixed";
-  /** Required iff `gimbalPitchMode === "fixed"`. `[-90, -30]`. */
-  gimbalPitchAngle?: Degrees;
-  /** M4E only. */
-  quickOrthoMappingEnable?: boolean;
-  /** Required iff `quickOrthoMappingEnable === true`. `[10, 30]`. */
-  quickOrthoMappingPitch?: Degrees;
-
-  Placemark: TemplatePolygonPlacemark;
+  /** Holds the survey polygon AND all shooting/mapping params (per WPML nesting). */
+  Placemark: Mapping2dPlacemark;
 }
 
 // ─── mapping3d (oblique photography) ─────────────────────────────────────────
@@ -121,19 +85,8 @@ export interface Mapping3dFolder {
   waylineCoordinateSysParam: WaylineCoordinateSysParam;
   autoFlightSpeed: MetersPerSecond;
   payloadParam?: PayloadParam;
-
-  caliFlightEnable?: boolean;
-  inclinedGimbalPitch: Degrees;
-  /** Range `[1, 15]`. */
-  inclinedFlightSpeed: MetersPerSecond;
-  shootType: ShootType;
-  direction: Degrees;
-  margin: number;
-  overlap: Overlap;
-  ellipsoidHeight: Meters;
-  height: Meters;
-
-  Placemark: TemplatePolygonPlacemark;
+  /** Holds the survey polygon AND all shooting/mapping params. */
+  Placemark: Mapping3dPlacemark;
 }
 
 // ─── mappingStrip ────────────────────────────────────────────────────────────
@@ -148,23 +101,6 @@ export interface MappingStripFolder {
   waylineCoordinateSysParam: WaylineCoordinateSysParam;
   autoFlightSpeed: MetersPerSecond;
   payloadParam?: PayloadParam;
-
-  caliFlightEnable: boolean;
-  shootType: ShootType;
-  direction: Degrees;
-  /** Float meters (vs integer in mapping2d/3d). */
-  margin: number;
-  singleLineEnable: boolean;
-  cuttingDistance: number;
-  boundaryOptimEnable: boolean;
-  leftExtend: number;
-  rightExtend: number;
-  includeCenterEnable: boolean;
-  overlap: Overlap;
-  ellipsoidHeight: Meters;
-  height: Meters;
-  /** When true, altitudes are read from LineString triples. */
-  stripUseTemplateAltitude: boolean;
-
-  Placemark: TemplateLineStringPlacemark;
+  /** Holds the LineString AND all strip params. */
+  Placemark: MappingStripPlacemark;
 }

package/src/types/waylines.ts

@@ -1,9 +1,18 @@
 import type { MetersPerSecond } from "./branded.js";
-import type { ActionGroup } from "./action.js";
+import type { Action } from "./action.js";
 import type { ExecuteHeightMode } from "./enums.js";
 import type { MissionConfig } from "./mission-config.js";
 import type { WaylinesPlacemark } from "./placemark.js";
 
+/**
+ * Pre-flight action list executed before the wayline starts.
+ * The XML `<wpml:startActionGroup>` element only wraps raw `<wpml:action>` items —
+ * it has no `actionGroupId`, `actionGroupMode`, or `actionTrigger` elements.
+ */
+export interface StartActionGroup {
+  action: Action[];
+}
+
 /**
  * `waylines.wpml` document. Mirrors `<kml><Document>` structure.
  * See `docs/kmz/waylines-wpml.html`.
@@ -24,9 +33,9 @@ export interface WaylinesFolder {
   /** Range `[1, 15]`. */
   autoFlightSpeed: MetersPerSecond;
   /**
-   * Optional pre-wayline action group.
+   * Optional pre-wayline action list executed before the wayline starts.
    * Available on M30/M30T, M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T.
    */
-  startActionGroup?: ActionGroup;
+  startActionGroup?: StartActionGroup;
   Placemark: WaylinesPlacemark[];
 }

package/src/types/waypoint-params.ts

@@ -19,7 +19,14 @@ export interface WaypointHeadingParam {
   waypointHeadingAngle?: Degrees;
   /** Required iff `waypointHeadingMode === "towardPOI"`. Z aim unsupported; set height to 0. */
   waypointPoiPoint?: LngLatHeight;
+  /**
+   * Whether `waypointHeadingAngle` is in effect at this waypoint.
+   * Observed in mapping waylines exports; `false` on the terminal waypoint.
+   */
+  waypointHeadingAngleEnable?: boolean;
   waypointHeadingPathMode: WaypointHeadingPathMode;
+  /** POI index when `waypointHeadingMode === "towardPOI"`. Default 0. */
+  waypointHeadingPoiIndex?: number;
 }
 
 /**
@@ -50,6 +57,17 @@ export interface WaylineCoordinateSysParam {
   surfaceFollowModeEnable?: boolean;
   /** Required iff `surfaceFollowModeEnable === true`. */
   surfaceRelativeHeight?: Meters;
+  /**
+   * ⚠️ NON-SPEC — observed in real DJI KMZ exports, absent from WPML 1.15 docs.
+   * When true, surface-follow uses live onboard sensor height (no DSM file).
+   */
+  isRealtimeSurfaceFollow?: boolean;
+  /**
+   * ⚠️ NON-SPEC — observed in real DJI KMZ exports, absent from WPML 1.15 docs.
+   * Path inside the KMZ to the DSM `.tif` used for surface-follow,
+   * e.g. `"wpmz/res/dsm/foo.tif"`. Only set when `isRealtimeSurfaceFollow` is false.
+   */
+  dsmFile?: string;
 }
 
 /**