@lumikmz/kmz 0.7.0 → 0.8.0

package/package.json

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

package/src/index.ts

@@ -1,4 +1,10 @@
 export * from "./types/index.js";
 export { plan, type PlanOptions } from "./plan/index.js";
+export {
+  deriveMappingStrip,
+  type MappingStripDerived,
+  type MappingStripRegion,
+  type MappingStripRegionRoute,
+} from "./plan/plan-mapping-strip.js";
 export { validate } from "./validate/index.js";
 export { haversineMeters } from "./plan/geometry.js";

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/plan/index.ts

@@ -27,7 +27,13 @@ import { planWaypoint } from "./plan-waypoint.js";
  */
 export interface PlanOptions {
   lineSpacing?: Meters;
+  crossTrackFootprint?: Meters;
+  photoSpacing?: Meters;
   shootInterval?: number;
+  /** mappingStrip UI layout mode; kept outside WPML until DJI direction encoding is verified. */
+  stripDirection?: "parallel" | "perpendicular";
+  /** Reverse mappingStrip region execution without changing region identities. */
+  regionOrderReversed?: boolean;
   resolveExecuteHeight?: (point: {
     lng: number;
     lat: number;
@@ -52,6 +58,6 @@ export function plan(template: Template, options?: PlanOptions): Waylines {
   if (isWaypoint(template)) return planWaypoint(template);
   if (isMapping2d(template)) return planMapping2d(template, options);
   if (isMapping3d(template)) return planMapping3d(template, options);
-  if (isMappingStrip(template)) return planMappingStrip(template);
+  if (isMappingStrip(template)) return planMappingStrip(template, options);
   throw new PlannerError(`Unknown templateType: ${(template as Template).Folder.templateType}`);
 }