@lumikmz/kmz 0.6.4 → 0.7.1

package/dist/index.d.mts

@@ -572,8 +572,19 @@ interface MegaphoneParam {
   megaphoneFileMd5: string;
   /** 1=8000, 2=16000, 3=24000, 4=32000, 5=48000, 6=64000 (only 4 supported today). */
   megaphoneFileBitrate: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Non-spec DJI Pilot TTS params observed in M4D/M4TD megaphone actions. */
+  ttsparam?: MegaphoneTtsParam;
 }
 type MegaphoneAction = ActionBase<"megaphone", MegaphoneParam>;
+interface MegaphoneTtsParam {
+  text: string;
+  role: "male" | "female";
+  language: "CN";
+  /** 0-100. */
+  volume: number;
+  /** 0-100. DJI Pilot exports commonly use 50. */
+  speed: number;
+}
 /** M4D/M4TD only — starts gimbal swing in smart-oblique mode. */
 interface SmartObliquePoint {
   /** seconds before this pose starts; DJI exports currently use 0. */
@@ -943,4 +954,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, 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 };
+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, MegaphoneTtsParam, 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

@@ -184,6 +184,7 @@ const PayloadEnum = {
 const EARTH_RADIUS = 6371e3;
 const DEG2RAD = Math.PI / 180;
 const RAD2DEG = 180 / Math.PI;
+const ANGLE_EPS_RAD = 1e-12;
 /** Project lng/lat to local ENU meters around `origin`. */
 function lngLatToEnu(point, origin) {
 	const dLat = (point.lat - origin.lat) * DEG2RAD;
@@ -290,6 +291,7 @@ function dedupeRing(ring, epsM = .5) {
 }
 /** Beyond this multiple of `distM`, a corner miter is clamped to avoid spikes. */
 const OFFSET_MITER_LIMIT = 2.5;
+const MIN_SCAN_SEGMENT_LEN_M = 1e-6;
 /**
 * Outward-offset (dilate) a simple polygon ring by `distM` meters in ENU.
 * Each vertex moves along the bisector of its two adjacent outward edge normals
@@ -335,6 +337,28 @@ function offsetPolygon(ring, distM) {
 	return out;
 }
 /**
+* Pull same-side boustrophedon turn points inward until adjacent flight lines
+* share one x coordinate. This keeps margin=0 routes inside the polygon while
+* avoiding very acute boundary-following connectors on slanted edges.
+*/
+function stabilizeTurnCorridors(segments) {
+	const segmentPts = segments.map(({ a, b, y, leftToRight }) => leftToRight ? [[a, y], [b, y]] : [[b, y], [a, y]]);
+	for (let i = 0; i + 1 < segments.length; i++) {
+		const cur = segments[i];
+		const next = segments[i + 1];
+		if (cur.leftToRight === next.leftToRight) continue;
+		const overlapMin = Math.max(cur.a, next.a);
+		const overlapMax = Math.min(cur.b, next.b);
+		if (overlapMin > overlapMax) continue;
+		const turnX = cur.leftToRight ? overlapMax : overlapMin;
+		segmentPts[i][1] = [turnX, cur.y];
+		segmentPts[i + 1][0] = [turnX, next.y];
+	}
+	const pts = [];
+	for (const [start, end] of segmentPts) pts.push(start, end);
+	return pts;
+}
+/**
 * Boustrophedon survey grid over an arbitrary simple polygon, aligned to `directionDeg`.
 * Flight lines run parallel to the heading; consecutive lines step by `lineSpacing`.
 * `marginM` extends each line lengthwise past the polygon edge.
@@ -344,7 +368,8 @@ function offsetPolygon(ring, distM) {
 function surveyGrid(ring, opts) {
 	const { directionDeg, marginM, lineSpacing, phaseOffsetM = 0, lengthwiseShiftM = 0 } = opts;
 	const t = directionDeg * DEG2RAD;
-	const alpha = Math.atan2(Math.cos(t), Math.sin(t));
+	const rawAlpha = Math.atan2(Math.cos(t), Math.sin(t));
+	const alpha = Math.abs(rawAlpha) < ANGLE_EPS_RAD ? 0 : rawAlpha;
 	const scanRing = ring.map((p) => rotateEnu(p, -alpha));
 	let minY = Infinity;
 	let maxY = -Infinity;
@@ -352,18 +377,25 @@ function surveyGrid(ring, opts) {
 		if (y < minY) minY = y;
 		if (y > maxY) maxY = y;
 	}
-	const scanPts = [];
+	const scanSegments = [];
 	let leftToRight = true;
 	for (let y = minY + phaseOffsetM; y <= maxY + lineSpacing * .5; y += lineSpacing) {
+		let emitted = false;
 		for (const [x1, x2] of clipHorizontal(y, scanRing)) {
+			if (Math.abs(x2 - x1) < MIN_SCAN_SEGMENT_LEN_M) continue;
 			const a = x1 - marginM + lengthwiseShiftM;
 			const b = x2 + marginM + lengthwiseShiftM;
-			if (leftToRight) scanPts.push([a, y], [b, y]);
-			else scanPts.push([b, y], [a, y]);
+			scanSegments.push({
+				a,
+				b,
+				y,
+				leftToRight
+			});
+			emitted = true;
 		}
-		leftToRight = !leftToRight;
+		if (emitted) leftToRight = !leftToRight;
 	}
-	return scanPts.map((p) => rotateEnu(p, alpha));
+	return stabilizeTurnCorridors(scanSegments).map((p) => rotateEnu(p, alpha));
 }
 //#endregion
 //#region src/plan/plan-mapping2d.ts

package/package.json

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

package/src/plan/geometry.test.ts

@@ -93,4 +93,22 @@ describe("surveyGrid", () => {
     const span = (pts: EnuPoint[]) => Math.abs(pts[1]![0] - pts[0]![0]);
     expect(span(widened)).toBeGreaterThan(span(base));
   });
+
+  it("keeps same-side turns inside the polygon instead of following acute slanted edges", () => {
+    const trapezoid: EnuPoint[] = [
+      [0, 0],
+      [120, 0],
+      [80, 100],
+      [0, 100],
+    ];
+    const pts = surveyGrid(trapezoid, { directionDeg: 90, marginM: 0, lineSpacing: 25 });
+
+    // First turn is on the right side. The lower endpoint is pulled back from
+    // x=120 to the next line's right boundary x=110, making a vertical in-area
+    // connector instead of an acute diagonal along the slanted edge.
+    expect(pts[1]![0]).toBeCloseTo(pts[2]![0], 3);
+    expect(pts[1]![0]).toBeCloseTo(110, 3);
+    expect(pts[1]![1]).toBeCloseTo(0, 3);
+    expect(pts[2]![1]).toBeCloseTo(25, 3);
+  });
 });

package/src/plan/geometry.ts

@@ -3,6 +3,7 @@ import type { LngLat } from "../types/branded.js";
 const EARTH_RADIUS = 6_371_000;
 const DEG2RAD = Math.PI / 180;
 const RAD2DEG = 180 / Math.PI;
+const ANGLE_EPS_RAD = 1e-12;
 
 export type EnuPoint = readonly [number, number];
 
@@ -133,6 +134,7 @@ function dedupeRing(ring: readonly EnuPoint[], epsM = 0.5): EnuPoint[] {
 
 /** Beyond this multiple of `distM`, a corner miter is clamped to avoid spikes. */
 const OFFSET_MITER_LIMIT = 2.5;
+const MIN_SCAN_SEGMENT_LEN_M = 1e-6;
 
 /**
  * Outward-offset (dilate) a simple polygon ring by `distM` meters in ENU.
@@ -208,6 +210,51 @@ export interface SurveyGridOptions {
   lengthwiseShiftM?: number;
 }
 
+interface ScanSegment {
+  a: number;
+  b: number;
+  y: number;
+  leftToRight: boolean;
+}
+
+/**
+ * Pull same-side boustrophedon turn points inward until adjacent flight lines
+ * share one x coordinate. This keeps margin=0 routes inside the polygon while
+ * avoiding very acute boundary-following connectors on slanted edges.
+ */
+function stabilizeTurnCorridors(segments: ScanSegment[]): EnuPoint[] {
+  const segmentPts = segments.map(({ a, b, y, leftToRight }) =>
+    leftToRight
+      ? ([
+          [a, y],
+          [b, y],
+        ] as [EnuPoint, EnuPoint])
+      : ([
+          [b, y],
+          [a, y],
+        ] as [EnuPoint, EnuPoint]),
+  );
+
+  for (let i = 0; i + 1 < segments.length; i++) {
+    const cur = segments[i]!;
+    const next = segments[i + 1]!;
+    if (cur.leftToRight === next.leftToRight) continue;
+
+    const overlapMin = Math.max(cur.a, next.a);
+    const overlapMax = Math.min(cur.b, next.b);
+    if (overlapMin > overlapMax) continue;
+
+    // LTR -> RTL turns on the right edge; RTL -> LTR turns on the left edge.
+    const turnX = cur.leftToRight ? overlapMax : overlapMin;
+    segmentPts[i]![1] = [turnX, cur.y];
+    segmentPts[i + 1]![0] = [turnX, next.y];
+  }
+
+  const pts: EnuPoint[] = [];
+  for (const [start, end] of segmentPts) pts.push(start, end);
+  return pts;
+}
+
 /**
  * Boustrophedon survey grid over an arbitrary simple polygon, aligned to `directionDeg`.
  * Flight lines run parallel to the heading; consecutive lines step by `lineSpacing`.
@@ -219,7 +266,8 @@ export function surveyGrid(ring: readonly EnuPoint[], opts: SurveyGridOptions):
   const { directionDeg, marginM, lineSpacing, phaseOffsetM = 0, lengthwiseShiftM = 0 } = opts;
   // Map the heading clockwise-from-north → CCW angle from +x axis
   const t = directionDeg * DEG2RAD;
-  const alpha = Math.atan2(Math.cos(t), Math.sin(t));
+  const rawAlpha = Math.atan2(Math.cos(t), Math.sin(t));
+  const alpha = Math.abs(rawAlpha) < ANGLE_EPS_RAD ? 0 : rawAlpha;
   const scanRing = ring.map((p) => rotateEnu(p, -alpha));
 
   let minY = Infinity;
@@ -229,17 +277,20 @@ export function surveyGrid(ring: readonly EnuPoint[], opts: SurveyGridOptions):
     if (y > maxY) maxY = y;
   }
 
-  const scanPts: EnuPoint[] = [];
+  const scanSegments: ScanSegment[] = [];
   let leftToRight = true;
   for (let y = minY + phaseOffsetM; y <= maxY + lineSpacing * 0.5; y += lineSpacing) {
+    let emitted = false;
     for (const [x1, x2] of clipHorizontal(y, scanRing)) {
+      if (Math.abs(x2 - x1) < MIN_SCAN_SEGMENT_LEN_M) continue;
       const a = x1 - marginM + lengthwiseShiftM;
       const b = x2 + marginM + lengthwiseShiftM;
-      if (leftToRight) scanPts.push([a, y], [b, y]);
-      else scanPts.push([b, y], [a, y]);
+      scanSegments.push({ a, b, y, leftToRight });
+      emitted = true;
     }
-    leftToRight = !leftToRight;
+    if (emitted) leftToRight = !leftToRight;
   }
 
+  const scanPts = stabilizeTurnCorridors(scanSegments);
   return scanPts.map((p) => rotateEnu(p, alpha));
 }

package/src/types/action.ts

@@ -249,9 +249,21 @@ export interface MegaphoneParam {
   megaphoneFileMd5: string;
   /** 1=8000, 2=16000, 3=24000, 4=32000, 5=48000, 6=64000 (only 4 supported today). */
   megaphoneFileBitrate: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Non-spec DJI Pilot TTS params observed in M4D/M4TD megaphone actions. */
+  ttsparam?: MegaphoneTtsParam;
 }
 export type MegaphoneAction = ActionBase<"megaphone", MegaphoneParam>;
 
+export interface MegaphoneTtsParam {
+  text: string;
+  role: "male" | "female";
+  language: "CN";
+  /** 0-100. */
+  volume: number;
+  /** 0-100. DJI Pilot exports commonly use 50. */
+  speed: number;
+}
+
 /** M4D/M4TD only — starts gimbal swing in smart-oblique mode. */
 export interface SmartObliquePoint {
   /** seconds before this pose starts; DJI exports currently use 0. */