@lumikmz/kmz 0.6.2 → 0.6.4

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,11 @@ 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);
+	let nextGroupId = 0;
 	const placemarks = enuWps.map((enu, index) => {
 		const coord = enuToLngLat(enu, origin);
 		const isLast = index === lastIndex;
@@ -753,30 +755,8 @@ function emitSmartOblique(folder, origin, enuWps, options) {
 			},
 			...COMMON_WP_EXTRAS
 		};
-		if (index === 0) placemark.actionGroup = [{
-			actionGroupId: 0,
-			actionGroupStartIndex: 0,
-			actionGroupEndIndex: lastIndex,
-			actionGroupMode: "sequence",
-			actionTrigger: { actionTriggerType: "reachPoint" },
-			action: [{
-				actionId: 0,
-				actionActuatorFunc: "startSmartOblique",
-				actionActuatorFuncParam: { payloadPositionIndex: 0 }
-			}]
-		}];
-		else if (isLast) placemark.actionGroup = [{
-			actionGroupId: 1,
-			actionGroupStartIndex: lastIndex,
-			actionGroupEndIndex: lastIndex,
-			actionGroupMode: "sequence",
-			actionTrigger: { actionTriggerType: "reachPoint" },
-			action: [{
-				actionId: 0,
-				actionActuatorFunc: "stopSmartOblique",
-				actionActuatorFuncParam: { payloadPositionIndex: 0 }
-			}]
-		}];
+		if (index % 2 === 0 && index + 1 <= lastIndex) placemark.actionGroup = [smartObliqueStartGroup(index, index + 1, nextGroupId++, smartObliquePoints)];
+		else if (index % 2 === 1) placemark.actionGroup = [smartObliqueStopGroup(index, nextGroupId++)];
 		return placemark;
 	});
 	return {
@@ -788,6 +768,65 @@ function emitSmartOblique(folder, origin, enuWps, options) {
 		Placemark: placemarks
 	};
 }
+function smartObliqueStartGroup(startIndex, endIndex, groupId, smartObliquePoints) {
+	return {
+		actionGroupId: groupId,
+		actionGroupStartIndex: startIndex,
+		actionGroupEndIndex: endIndex,
+		actionGroupMode: "sequence",
+		actionTrigger: { actionTriggerType: "betweenAdjacentPoints" },
+		action: [{
+			actionId: 0,
+			actionActuatorFunc: "gimbalAngleLock",
+			actionActuatorFuncParam: { payloadPositionIndex: 0 }
+		}, {
+			actionId: 1,
+			actionActuatorFunc: "startSmartOblique",
+			actionActuatorFuncParam: {
+				smartObliqueCycleMode: "unlimited",
+				payloadPositionIndex: 0,
+				smartObliquePoint: smartObliquePoints
+			}
+		}]
+	};
+}
+function smartObliqueStopGroup(index, groupId) {
+	return {
+		actionGroupId: groupId,
+		actionGroupStartIndex: index,
+		actionGroupEndIndex: index,
+		actionGroupMode: "sequence",
+		actionTrigger: { actionTriggerType: "reachPoint" },
+		action: [{
+			actionId: 0,
+			actionActuatorFunc: "stopSmartOblique",
+			actionActuatorFuncParam: { payloadPositionIndex: 0 }
+		}, {
+			actionId: 1,
+			actionActuatorFunc: "gimbalAngleUnlock"
+		}]
+	};
+}
+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 +834,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumikmz/kmz",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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,13 @@ 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);
+  let nextGroupId = 0;
 
   const placemarks: WaylinesPlacemark[] = enuWps.map((enu, index) => {
     const coord = enuToLngLat(enu, origin);
@@ -490,40 +493,12 @@ function emitSmartOblique(
             },
       ...COMMON_WP_EXTRAS,
     };
-    if (index === 0) {
-      placemark.actionGroup = [
-        {
-          actionGroupId: 0,
-          actionGroupStartIndex: 0,
-          actionGroupEndIndex: lastIndex,
-          actionGroupMode: "sequence",
-          actionTrigger: { actionTriggerType: "reachPoint" },
-          action: [
-            {
-              actionId: 0,
-              actionActuatorFunc: "startSmartOblique",
-              actionActuatorFuncParam: { payloadPositionIndex: 0 },
-            },
-          ],
-        },
-      ];
-    } else if (isLast) {
+    if (index % 2 === 0 && index + 1 <= lastIndex) {
       placemark.actionGroup = [
-        {
-          actionGroupId: 1,
-          actionGroupStartIndex: lastIndex,
-          actionGroupEndIndex: lastIndex,
-          actionGroupMode: "sequence",
-          actionTrigger: { actionTriggerType: "reachPoint" },
-          action: [
-            {
-              actionId: 0,
-              actionActuatorFunc: "stopSmartOblique",
-              actionActuatorFuncParam: { payloadPositionIndex: 0 },
-            },
-          ],
-        },
+        smartObliqueStartGroup(index, index + 1, nextGroupId++, smartObliquePoints),
       ];
+    } else if (index % 2 === 1) {
+      placemark.actionGroup = [smartObliqueStopGroup(index, nextGroupId++)];
     }
     return placemark;
   });
@@ -538,6 +513,78 @@ function emitSmartOblique(
   };
 }
 
+function smartObliqueStartGroup(
+  startIndex: number,
+  endIndex: number,
+  groupId: number,
+  smartObliquePoints: SmartObliquePoint[],
+) {
+  return {
+    actionGroupId: groupId,
+    actionGroupStartIndex: startIndex,
+    actionGroupEndIndex: endIndex,
+    actionGroupMode: "sequence" as const,
+    actionTrigger: { actionTriggerType: "betweenAdjacentPoints" as const },
+    action: [
+      {
+        actionId: 0,
+        actionActuatorFunc: "gimbalAngleLock" as const,
+        actionActuatorFuncParam: { payloadPositionIndex: 0 },
+      },
+      {
+        actionId: 1,
+        actionActuatorFunc: "startSmartOblique" as const,
+        actionActuatorFuncParam: {
+          smartObliqueCycleMode: "unlimited" as const,
+          payloadPositionIndex: 0,
+          smartObliquePoint: smartObliquePoints,
+        },
+      },
+    ],
+  };
+}
+
+function smartObliqueStopGroup(index: number, groupId: number) {
+  return {
+    actionGroupId: groupId,
+    actionGroupStartIndex: index,
+    actionGroupEndIndex: index,
+    actionGroupMode: "sequence" as const,
+    actionTrigger: { actionTriggerType: "reachPoint" as const },
+    action: [
+      {
+        actionId: 0,
+        actionActuatorFunc: "stopSmartOblique" as const,
+        actionActuatorFuncParam: { payloadPositionIndex: 0 },
+      },
+      { actionId: 1, actionActuatorFunc: "gimbalAngleUnlock" as const },
+    ],
+  };
+}
+
+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 +603,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.test.ts

@@ -370,8 +370,40 @@ describe("plan", () => {
     const funcs = wl.Folder[0]!.Placemark.flatMap((p) =>
       (p.actionGroup ?? []).flatMap((g) => g.action.map((a) => a.actionActuatorFunc)),
     );
+    const scanlineCount = Math.floor(wl.Folder[0]!.Placemark.length / 2);
+    expect(funcs.filter((fn) => fn === "startSmartOblique")).toHaveLength(scanlineCount);
+    expect(funcs.filter((fn) => fn === "stopSmartOblique")).toHaveLength(scanlineCount);
+    expect(funcs).toContain("gimbalAngleLock");
     expect(funcs).toContain("startSmartOblique");
     expect(funcs).toContain("stopSmartOblique");
+    expect(funcs).toContain("gimbalAngleUnlock");
+
+    const groups = wl.Folder[0]!.Placemark.flatMap((p) => p.actionGroup ?? []);
+    const firstStartGroup = groups.find((g) =>
+      g.action.some((a) => a.actionActuatorFunc === "startSmartOblique"),
+    )!;
+    expect(firstStartGroup.actionGroupStartIndex).toBe(0);
+    expect(firstStartGroup.actionGroupEndIndex).toBe(1);
+    expect(firstStartGroup.actionTrigger.actionTriggerType).toBe("betweenAdjacentPoints");
+
+    const firstStopGroup = groups.find((g) =>
+      g.action.some((a) => a.actionActuatorFunc === "stopSmartOblique"),
+    )!;
+    expect(firstStopGroup.actionGroupStartIndex).toBe(1);
+    expect(firstStopGroup.actionGroupEndIndex).toBe(1);
+    expect(firstStopGroup.actionTrigger.actionTriggerType).toBe("reachPoint");
+
+    const start = firstStartGroup.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>;