@lumikmz/kmz 0.6.1 → 0.6.3

package/dist/index.d.mts

@@ -575,8 +575,20 @@ interface MegaphoneParam {
 }
 type MegaphoneAction = ActionBase<"megaphone", MegaphoneParam>;
 /** M4D/M4TD only — starts gimbal swing in smart-oblique mode. */
+interface SmartObliquePoint {
+  /** seconds before this pose starts; DJI exports currently use 0. */
+  smartObliqueRunningTime: number;
+  /** seconds to hold this pose for smart-oblique shooting. */
+  smartObliqueStayTime: number;
+  smartObliqueEulerPitch: Degrees;
+  smartObliqueEulerRoll: Degrees;
+  smartObliqueEulerYaw: Degrees;
+}
 interface StartSmartObliqueParam {
+  /** Observed in DJI exports; older generated files may omit it. */
+  smartObliqueCycleMode?: "unlimited";
   payloadPositionIndex: number;
+  smartObliquePoint?: SmartObliquePoint[];
 }
 type StartSmartObliqueAction = ActionBase<"startSmartOblique", StartSmartObliqueParam>;
 /** M4D/M4TD only — stops gimbal swing in smart-oblique mode. */
@@ -931,4 +943,4 @@ declare function validate(doc: Template | Waylines): Issue[];
 /** Great-circle distance between two WGS-84 coordinates, in meters. */
 declare function haversineMeters(a: LngLat, b: LngLat): number;
 //#endregion
-export { AccurateShootAction, AccurateShootParam, Action, ActionActuatorFunc, ActionGroup, ActionGroupMode, ActionTrigger, ActionTriggerType, AircraftPathMode, AutoRerouteInfo, CoordinateMode, CustomDirNameAction, CustomDirNameParam, Degrees, DroneEnum, DroneInfo, ExecuteHeightMode, ExecuteRCLostAction, ExitOnRCLost, FinishAction, FlyToWaylineMode, FocusAction, FocusMode, FocusParam, GimbalAngleLockAction, GimbalAngleLockParam, GimbalAngleUnlockAction, GimbalEvenlyRotateAction, GimbalEvenlyRotateParam, GimbalHeadingYawBase, GimbalPitchMode, GimbalRotateAction, GimbalRotateMode, GimbalRotateParam, HoverAction, HoverParam, Issue, KmzError, LensType, LidarReturnMode, LidarScanningMode, LngLat, LngLatHeight, Mapping2dFolder, Mapping2dPlacemark, Mapping2dTemplate, Mapping3dFolder, Mapping3dPlacemark, Mapping3dTemplate, MappingHeadingMode, MappingHeadingParam, MappingStripFolder, MappingStripPlacemark, MappingStripTemplate, MegaphoneAction, MegaphoneParam, MeteringMode, Meters, MetersPerSecond, MissionConfig, OrientedPhotoMode, OrientedShootAction, OrientedShootParam, Overlap, PanoShotAction, PanoShotParam, PanoShotSubMode, PayloadEnum, PayloadInfo, PayloadParam, type PlanOptions, PlannerError, PositioningType, RecordPointCloudAction, RecordPointCloudOperate, RecordPointCloudParam, RotateYawAction, RotateYawParam, SearchlightAction, SearchlightParam, SetFocusTypeAction, SetFocusTypeParam, ShootType, StartActionGroup, StartRecordAction, StartRecordParam, StartSmartObliqueAction, StartSmartObliqueParam, StartTimeLapseAction, StartTimeLapseParam, StopRecordAction, StopRecordParam, StopSmartObliqueAction, StopSmartObliqueParam, StopTimeLapseAction, StopTimeLapseParam, TakePhotoAction, TakePhotoParam, Template, TemplateHeightMode, TemplatePolygon, TemplateType, TemplateWaypointPlacemark, WaylineCoordinateSysParam, Waylines, WaylinesFolder, WaylinesPlacemark, WaypointFolder, WaypointHeadingMode, WaypointHeadingParam, WaypointHeadingPathMode, WaypointTemplate, WaypointTurnMode, WaypointTurnParam, ZoomAction, ZoomParam, degrees, haversineMeters, meters, metersPerSecond, plan, validate };
+export { AccurateShootAction, AccurateShootParam, Action, ActionActuatorFunc, ActionGroup, ActionGroupMode, ActionTrigger, ActionTriggerType, AircraftPathMode, AutoRerouteInfo, CoordinateMode, CustomDirNameAction, CustomDirNameParam, Degrees, DroneEnum, DroneInfo, ExecuteHeightMode, ExecuteRCLostAction, ExitOnRCLost, FinishAction, FlyToWaylineMode, FocusAction, FocusMode, FocusParam, GimbalAngleLockAction, GimbalAngleLockParam, GimbalAngleUnlockAction, GimbalEvenlyRotateAction, GimbalEvenlyRotateParam, GimbalHeadingYawBase, GimbalPitchMode, GimbalRotateAction, GimbalRotateMode, GimbalRotateParam, HoverAction, HoverParam, Issue, KmzError, LensType, LidarReturnMode, LidarScanningMode, LngLat, LngLatHeight, Mapping2dFolder, Mapping2dPlacemark, Mapping2dTemplate, Mapping3dFolder, Mapping3dPlacemark, Mapping3dTemplate, MappingHeadingMode, MappingHeadingParam, MappingStripFolder, MappingStripPlacemark, MappingStripTemplate, MegaphoneAction, MegaphoneParam, MeteringMode, Meters, MetersPerSecond, MissionConfig, OrientedPhotoMode, OrientedShootAction, OrientedShootParam, Overlap, PanoShotAction, PanoShotParam, PanoShotSubMode, PayloadEnum, PayloadInfo, PayloadParam, type PlanOptions, PlannerError, PositioningType, RecordPointCloudAction, RecordPointCloudOperate, RecordPointCloudParam, RotateYawAction, RotateYawParam, SearchlightAction, SearchlightParam, SetFocusTypeAction, SetFocusTypeParam, ShootType, SmartObliquePoint, StartActionGroup, StartRecordAction, StartRecordParam, StartSmartObliqueAction, StartSmartObliqueParam, StartTimeLapseAction, StartTimeLapseParam, StopRecordAction, StopRecordParam, StopSmartObliqueAction, StopSmartObliqueParam, StopTimeLapseAction, StopTimeLapseParam, TakePhotoAction, TakePhotoParam, Template, TemplateHeightMode, TemplatePolygon, TemplateType, TemplateWaypointPlacemark, WaylineCoordinateSysParam, Waylines, WaylinesFolder, WaylinesPlacemark, WaypointFolder, WaypointHeadingMode, WaypointHeadingParam, WaypointHeadingPathMode, WaypointTemplate, WaypointTurnMode, WaypointTurnParam, ZoomAction, ZoomParam, degrees, haversineMeters, meters, metersPerSecond, plan, validate };

package/dist/index.mjs

@@ -734,9 +734,10 @@ function emitOrtho(folder, origin, enuWps, shootInterval, options) {
 * Single-pass smart-oblique / quick-ortho (smartObliqueEnable=true):
 * The aircraft flies one grid while the gimbal swings (startSmartOblique/stopSmartOblique).
 */
-function emitSmartOblique(folder, origin, enuWps, options) {
+function emitSmartOblique(folder, origin, enuWps, shootInterval, options) {
 	const lastIndex = enuWps.length - 1;
 	const pitch = folder.Placemark.smartObliqueGimbalPitch ?? degrees(-45);
+	const smartObliquePoints = buildSmartObliquePoints(Number(pitch), shootInterval);
 	const placemarks = enuWps.map((enu, index) => {
 		const coord = enuToLngLat(enu, origin);
 		const isLast = index === lastIndex;
@@ -761,8 +762,16 @@ function emitSmartOblique(folder, origin, enuWps, options) {
 			actionTrigger: { actionTriggerType: "reachPoint" },
 			action: [{
 				actionId: 0,
-				actionActuatorFunc: "startSmartOblique",
+				actionActuatorFunc: "gimbalAngleLock",
 				actionActuatorFuncParam: { payloadPositionIndex: 0 }
+			}, {
+				actionId: 1,
+				actionActuatorFunc: "startSmartOblique",
+				actionActuatorFuncParam: {
+					smartObliqueCycleMode: "unlimited",
+					payloadPositionIndex: 0,
+					smartObliquePoint: smartObliquePoints
+				}
 			}]
 		}];
 		else if (isLast) placemark.actionGroup = [{
@@ -775,6 +784,9 @@ function emitSmartOblique(folder, origin, enuWps, options) {
 				actionId: 0,
 				actionActuatorFunc: "stopSmartOblique",
 				actionActuatorFuncParam: { payloadPositionIndex: 0 }
+			}, {
+				actionId: 1,
+				actionActuatorFunc: "gimbalAngleUnlock"
 			}]
 		}];
 		return placemark;
@@ -788,6 +800,26 @@ function emitSmartOblique(folder, origin, enuWps, options) {
 		Placemark: placemarks
 	};
 }
+function buildSmartObliquePoints(pitchDeg, shootInterval) {
+	const stayTime = Math.max(.1, shootInterval);
+	const obliquePitch = -Math.abs(pitchDeg || 45);
+	return [
+		smartObliquePoint(-90, 0, 0),
+		smartObliquePoint(obliquePitch, 45, stayTime),
+		smartObliquePoint(obliquePitch, -45, stayTime),
+		smartObliquePoint(-120, 50, stayTime),
+		smartObliquePoint(-120, -50, stayTime)
+	];
+}
+function smartObliquePoint(pitchDeg, yawDeg, stayTime) {
+	return {
+		smartObliqueRunningTime: 0,
+		smartObliqueStayTime: stayTime,
+		smartObliqueEulerPitch: degrees(pitchDeg),
+		smartObliqueEulerRoll: degrees(0),
+		smartObliqueEulerYaw: degrees(yawDeg)
+	};
+}
 function planMapping2d(template, options) {
 	if (options?.lineSpacing == null) throw new PlannerError("mapping2d requires options.lineSpacing — calculate 2·h·tan(HFOV/2)·(1−sideOverlap) in the demo and pass it in.");
 	const standoff = template.Folder.Placemark.smartObliqueEnable === true ? smartObliqueStandoff(template.Folder) : 0;
@@ -795,7 +827,7 @@ function planMapping2d(template, options) {
 	const shootInterval = options.shootInterval ?? 2;
 	if (folder.Placemark.smartObliqueEnable === true) return {
 		missionConfig: template.missionConfig,
-		Folder: [emitSmartOblique(folder, origin, enuWps, options)]
+		Folder: [emitSmartOblique(folder, origin, enuWps, shootInterval, options)]
 	};
 	return {
 		missionConfig: template.missionConfig,
@@ -1061,7 +1093,7 @@ function planWaypoint(template) {
 	const placemarks = folder.Placemark.map((p, i) => {
 		const heading = p.useGlobalHeadingParam || p.waypointHeadingParam === void 0 ? folder.globalWaypointHeadingParam : p.waypointHeadingParam;
 		const turn = p.useGlobalTurnParam || p.waypointTurnParam === void 0 ? { waypointTurnMode: folder.globalWaypointTurnMode } : p.waypointTurnParam;
-		const executeHeight = p.useGlobalHeight || p.height === void 0 ? folder.globalHeight : p.height;
+		const executeHeight = folder.waylineCoordinateSysParam.heightMode === "aboveGroundLevel" && p.ellipsoidHeight !== void 0 ? p.ellipsoidHeight : p.useGlobalHeight || p.height === void 0 ? folder.globalHeight : p.height;
 		const waypointSpeed = p.useGlobalSpeed || p.waypointSpeed === void 0 ? folder.autoFlightSpeed : p.waypointSpeed;
 		return {
 			Point: p.Point,
@@ -1090,13 +1122,13 @@ function planWaypoint(template) {
 /**
 * Map a template heightMode to a waylines executeHeightMode.
 * - `EGM96` → `WGS84` (waylines spec doesn't expose EGM96; runtime resolves it).
-* - `aboveGroundLevel` → `realTimeFollowSurface` (closest executable analog).
+* - `aboveGroundLevel` → `WGS84` (waypoint waylines use per-point ellipsoid heights).
 */
 function heightModeToExecuteMode(mode) {
 	switch (mode) {
-		case "EGM96": return "WGS84";
+		case "EGM96":
+		case "aboveGroundLevel": return "WGS84";
 		case "relativeToStartPoint": return "relativeToStartPoint";
-		case "aboveGroundLevel":
 		case "realTimeFollowSurface": return "realTimeFollowSurface";
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumikmz/kmz",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "DJI KMZ/WPML domain model + plan() algorithm + validate(), spec-aligned types mirroring docs/kmz/",
   "license": "MIT",
   "type": "module",

package/src/plan/plan-mapping2d.ts

@@ -1,5 +1,5 @@
 import { degrees, meters, type Meters } from "../types/branded.js";
-import type { Action } from "../types/action.js";
+import type { Action, SmartObliquePoint } from "../types/action.js";
 import type { ExecuteHeightMode } from "../types/enums.js";
 import type { Mapping2dFolder, Mapping2dTemplate } from "../types/template.js";
 import type { StartActionGroup } from "../types/waylines.js";
@@ -466,10 +466,12 @@ function emitSmartOblique(
   folder: Mapping2dFolder,
   origin: { lng: number; lat: number },
   enuWps: readonly EnuPoint[],
+  shootInterval: number,
   options?: PlanOptions,
 ): WaylinesFolder {
   const lastIndex = enuWps.length - 1;
   const pitch = folder.Placemark.smartObliqueGimbalPitch ?? degrees(-45);
+  const smartObliquePoints = buildSmartObliquePoints(Number(pitch), shootInterval);
 
   const placemarks: WaylinesPlacemark[] = enuWps.map((enu, index) => {
     const coord = enuToLngLat(enu, origin);
@@ -501,9 +503,18 @@ function emitSmartOblique(
           action: [
             {
               actionId: 0,
-              actionActuatorFunc: "startSmartOblique",
+              actionActuatorFunc: "gimbalAngleLock",
               actionActuatorFuncParam: { payloadPositionIndex: 0 },
             },
+            {
+              actionId: 1,
+              actionActuatorFunc: "startSmartOblique",
+              actionActuatorFuncParam: {
+                smartObliqueCycleMode: "unlimited",
+                payloadPositionIndex: 0,
+                smartObliquePoint: smartObliquePoints,
+              },
+            },
           ],
         },
       ];
@@ -521,6 +532,7 @@ function emitSmartOblique(
               actionActuatorFunc: "stopSmartOblique",
               actionActuatorFuncParam: { payloadPositionIndex: 0 },
             },
+            { actionId: 1, actionActuatorFunc: "gimbalAngleUnlock" },
           ],
         },
       ];
@@ -538,6 +550,29 @@ function emitSmartOblique(
   };
 }
 
+function buildSmartObliquePoints(pitchDeg: number, shootInterval: number): SmartObliquePoint[] {
+  const stayTime = Math.max(0.1, shootInterval);
+  const obliquePitch = -Math.abs(pitchDeg || 45);
+
+  return [
+    smartObliquePoint(-90, 0, 0),
+    smartObliquePoint(obliquePitch, 45, stayTime),
+    smartObliquePoint(obliquePitch, -45, stayTime),
+    smartObliquePoint(-120, 50, stayTime),
+    smartObliquePoint(-120, -50, stayTime),
+  ];
+}
+
+function smartObliquePoint(pitchDeg: number, yawDeg: number, stayTime: number): SmartObliquePoint {
+  return {
+    smartObliqueRunningTime: 0,
+    smartObliqueStayTime: stayTime,
+    smartObliqueEulerPitch: degrees(pitchDeg),
+    smartObliqueEulerRoll: degrees(0),
+    smartObliqueEulerYaw: degrees(yawDeg),
+  };
+}
+
 export function planMapping2d(template: Mapping2dTemplate, options?: PlanOptions): Waylines {
   if (options?.lineSpacing == null) {
     throw new PlannerError(
@@ -556,7 +591,7 @@ export function planMapping2d(template: Mapping2dTemplate, options?: PlanOptions
   if (folder.Placemark.smartObliqueEnable === true) {
     return {
       missionConfig: template.missionConfig,
-      Folder: [emitSmartOblique(folder, origin, enuWps, options)],
+      Folder: [emitSmartOblique(folder, origin, enuWps, shootInterval, options)],
     };
   }
   // 正射 and 正射+智能摆拍 share the nadir grid; the centroid detour is driven by

package/src/plan/plan-waypoint.ts

@@ -25,7 +25,12 @@ export function planWaypoint(template: WaypointTemplate): Waylines {
         : p.waypointTurnParam;
 
     const executeHeight =
-      p.useGlobalHeight || p.height === undefined ? folder.globalHeight : p.height;
+      folder.waylineCoordinateSysParam.heightMode === "aboveGroundLevel" &&
+      p.ellipsoidHeight !== undefined
+        ? p.ellipsoidHeight
+        : p.useGlobalHeight || p.height === undefined
+          ? folder.globalHeight
+          : p.height;
 
     const waypointSpeed =
       p.useGlobalSpeed || p.waypointSpeed === undefined ? folder.autoFlightSpeed : p.waypointSpeed;
@@ -58,17 +63,17 @@ export function planWaypoint(template: WaypointTemplate): Waylines {
 /**
  * Map a template heightMode to a waylines executeHeightMode.
  * - `EGM96` → `WGS84` (waylines spec doesn't expose EGM96; runtime resolves it).
- * - `aboveGroundLevel` → `realTimeFollowSurface` (closest executable analog).
+ * - `aboveGroundLevel` → `WGS84` (waypoint waylines use per-point ellipsoid heights).
  */
 function heightModeToExecuteMode(
   mode: WaypointFolder["waylineCoordinateSysParam"]["heightMode"],
 ): ExecuteHeightMode {
   switch (mode) {
     case "EGM96":
+    case "aboveGroundLevel":
       return "WGS84";
     case "relativeToStartPoint":
       return "relativeToStartPoint";
-    case "aboveGroundLevel":
     case "realTimeFollowSurface":
       return "realTimeFollowSurface";
   }

package/src/plan/plan.test.ts

@@ -61,6 +61,52 @@ describe("plan", () => {
     expect(waylines.missionConfig).toBe(template.missionConfig);
   });
 
+  it("waypoint aboveGroundLevel uses per-point ellipsoid heights as WGS84 executeHeight", () => {
+    const template: WaypointTemplate = {
+      missionConfig,
+      Folder: {
+        templateType: "waypoint",
+        templateId: 0,
+        waylineCoordinateSysParam: { coordinateMode: "WGS84", heightMode: "aboveGroundLevel" },
+        autoFlightSpeed: metersPerSecond(10),
+        globalWaypointTurnMode: "toPointAndStopWithDiscontinuityCurvature",
+        gimbalPitchMode: "manual",
+        globalHeight: meters(50),
+        globalWaypointHeadingParam: {
+          waypointHeadingMode: "followWayline",
+          waypointHeadingPathMode: "followBadArc",
+        },
+        Placemark: [
+          {
+            Point: { coordinates: { lng: 113.938, lat: 22.5397 } },
+            index: 0,
+            useGlobalHeight: false,
+            height: meters(80),
+            ellipsoidHeight: meters(180),
+            useGlobalSpeed: true,
+            useGlobalHeadingParam: true,
+            useGlobalTurnParam: true,
+          },
+          {
+            Point: { coordinates: { lng: 113.939, lat: 22.5407 } },
+            index: 1,
+            useGlobalHeight: false,
+            height: meters(90),
+            ellipsoidHeight: meters(190),
+            useGlobalSpeed: true,
+            useGlobalHeadingParam: true,
+            useGlobalTurnParam: true,
+          },
+        ],
+      },
+    };
+
+    const waylines = plan(template);
+
+    expect(waylines.Folder[0]!.executeHeightMode).toBe("WGS84");
+    expect(waylines.Folder[0]!.Placemark.map((p) => Number(p.executeHeight))).toEqual([180, 190]);
+  });
+
   it("compiles a mapping2d template into a serpentine scan", () => {
     const template: Mapping2dTemplate = {
       missionConfig,
@@ -324,8 +370,26 @@ describe("plan", () => {
     const funcs = wl.Folder[0]!.Placemark.flatMap((p) =>
       (p.actionGroup ?? []).flatMap((g) => g.action.map((a) => a.actionActuatorFunc)),
     );
+    expect(funcs.filter((fn) => fn === "startSmartOblique")).toHaveLength(1);
+    expect(funcs.filter((fn) => fn === "stopSmartOblique")).toHaveLength(1);
+    expect(funcs).toContain("gimbalAngleLock");
     expect(funcs).toContain("startSmartOblique");
     expect(funcs).toContain("stopSmartOblique");
+    expect(funcs).toContain("gimbalAngleUnlock");
+
+    const start = wl.Folder[0]!.Placemark.flatMap((p) => p.actionGroup ?? [])
+      .flatMap((g) => g.action)
+      .find((a) => a.actionActuatorFunc === "startSmartOblique");
+    expect(start?.actionActuatorFunc).toBe("startSmartOblique");
+    if (start?.actionActuatorFunc === "startSmartOblique") {
+      expect(start.actionActuatorFuncParam.smartObliqueCycleMode).toBe("unlimited");
+      expect(start.actionActuatorFuncParam.smartObliquePoint).toHaveLength(5);
+      expect(
+        start.actionActuatorFuncParam.smartObliquePoint?.map((p) =>
+          Number(p.smartObliqueEulerPitch),
+        ),
+      ).toEqual([-90, -45, -45, -120, -120]);
+    }
 
     // The camera swings omnidirectionally, so the polygon is dilated by the
     // stand-off and the grid overflies the boundary on EVERY side. Polygon spans

package/src/types/action.ts

@@ -253,8 +253,21 @@ export interface MegaphoneParam {
 export type MegaphoneAction = ActionBase<"megaphone", MegaphoneParam>;
 
 /** M4D/M4TD only — starts gimbal swing in smart-oblique mode. */
+export interface SmartObliquePoint {
+  /** seconds before this pose starts; DJI exports currently use 0. */
+  smartObliqueRunningTime: number;
+  /** seconds to hold this pose for smart-oblique shooting. */
+  smartObliqueStayTime: number;
+  smartObliqueEulerPitch: Degrees;
+  smartObliqueEulerRoll: Degrees;
+  smartObliqueEulerYaw: Degrees;
+}
+
 export interface StartSmartObliqueParam {
+  /** Observed in DJI exports; older generated files may omit it. */
+  smartObliqueCycleMode?: "unlimited";
   payloadPositionIndex: number;
+  smartObliquePoint?: SmartObliquePoint[];
 }
 export type StartSmartObliqueAction = ActionBase<"startSmartOblique", StartSmartObliqueParam>;