@lumikmz/kmz 0.7.0 → 0.8.0

package/src/plan/plan-mapping-strip.ts

@@ -1,59 +1,94 @@
-import { degrees } from "../types/branded.js";
-import type { ExecuteHeightMode } from "../types/enums.js";
+import { degrees, meters, type LngLat, type Meters } from "../types/branded.js";
+import type { ActionGroup } from "../types/action.js";
+import type { ExecuteHeightMode, LensType } from "../types/enums.js";
+import { PlannerError } from "../types/errors.js";
 import type { MappingStripFolder, MappingStripTemplate } from "../types/template.js";
 import type { Waylines, WaylinesFolder } from "../types/waylines.js";
 import type { WaylinesPlacemark } from "../types/placemark.js";
-import { bearingDeg, centroid, lngLatToEnu } from "./geometry.js";
-
-/**
- * Compile a `mappingStrip` template into a single wayline that follows the
- * supplied LineString. Each LineString vertex becomes one waypoint.
- *
- * When `stripUseTemplateAltitude` is true the altitude in each LineString
- * triple is used as the executeHeight; otherwise the folder's `height` is used.
- */
-export function planMappingStrip(template: MappingStripTemplate): Waylines {
-  const folder = template.Folder;
-  const coords = parseTriples(folder.Placemark.LineString.coordinates);
-  const origin = centroid(coords.map((c) => ({ lng: c.lng, lat: c.lat })));
-  const enuPath = coords.map((c) => lngLatToEnu({ lng: c.lng, lat: c.lat }, origin));
-
-  const placemarks: WaylinesPlacemark[] = coords.map((c, index) => {
-    const isLast = index === coords.length - 1;
-    const headingAngle = isLast ? 0 : bearingDeg(enuPath[index]!, enuPath[index + 1]!);
-    const executeHeight =
-      folder.Placemark.stripUseTemplateAltitude && c.alt !== undefined
-        ? (c.alt as ReturnType<typeof folder.Placemark.height extends infer T ? () => T : never>)
-        : folder.Placemark.height;
+import {
+  bearingDeg,
+  centroid,
+  enuToLngLat,
+  haversineMeters,
+  lngLatToEnu,
+  surveyGrid,
+  type EnuPoint,
+} from "./geometry.js";
+import type { PlanOptions } from "./index.js";
 
-    return {
-      Point: { coordinates: { lng: c.lng, lat: c.lat } },
-      index,
-      executeHeight,
-      waypointSpeed: folder.autoFlightSpeed,
-      waypointHeadingParam: {
-        waypointHeadingMode: "followWayline",
-        waypointHeadingAngle: degrees(headingAngle),
-        waypointHeadingPathMode: "followBadArc",
-      },
-      waypointTurnParam: { waypointTurnMode: "toPointAndPassWithContinuityCurvature" },
-    };
-  });
+const POINT_EPS_M = 0.05;
+const MITER_LIMIT = 2.5;
+const MAX_ROUTE_COUNT = 1_000;
+const TURN_DAMPING_M = 10;
 
-  const waylineFolder: WaylinesFolder = {
-    templateId: folder.templateId,
-    waylineId: 0,
-    executeHeightMode: heightModeToExecuteMode(folder),
-    autoFlightSpeed: folder.autoFlightSpeed,
-    Placemark: placemarks,
-  };
+export interface MappingStripRegion {
+  id: string;
+  sourceRegionIndexes: number[];
+  startDistance: Meters;
+  endDistance: Meters;
+  centerLine: LngLat[];
+  polygon: LngLat[];
+}
+
+export interface MappingStripRegionRoute {
+  regionId: string;
+  routeOffsets: Meters[];
+  routeLines: LngLat[][];
+  segments: MappingStripRouteSegment[];
+  executablePath: LngLat[];
+  length: Meters;
+}
+
+export interface MappingStripRouteSegment {
+  kind: "work" | "turn" | "transit" | "elevationOptimize";
+  points: LngLat[];
+  photoEnabled: boolean;
+}
+
+export interface MappingStripDerived {
+  centerLineLength: Meters;
+  surveyArea: LngLat[];
+  surveyAreaSize: number;
+  regions: MappingStripRegion[];
+  flightRoutes: MappingStripRegionRoute[];
+  totalFlightLength: Meters;
+  photoSpacing: Meters;
+  estimatedPhotoCount: number;
+  estimatedDuration: number;
+}
+
+interface StripPlanInputs {
+  crossTrackFootprint: number;
+  lineSpacing: number;
+  photoSpacing: number;
+  shootInterval: number;
+}
+
+interface LocalRegion {
+  id: string;
+  sourceRegionIndexes: number[];
+  startDistance: number;
+  endDistance: number;
+  centerLine: EnuPoint[];
+  polygon: EnuPoint[];
+  beforePoint?: EnuPoint;
+  afterPoint?: EnuPoint;
+}
 
-  return { missionConfig: template.missionConfig, Folder: [waylineFolder] };
+interface LocalRouteSegment {
+  kind: "work" | "turn" | "elevationOptimize";
+  points: EnuPoint[];
+  photoEnabled: boolean;
 }
 
-interface Triple {
-  lng: number;
-  lat: number;
+interface LocalRouteCandidate {
+  lines: EnuPoint[][];
+  segments: LocalRouteSegment[];
+  start: EnuPoint;
+  end: EnuPoint;
+}
+
+interface Triple extends LngLat {
   alt?: number;
 }
 
@@ -61,6 +96,7 @@ function parseTriples(s: string): Triple[] {
   return s
     .trim()
     .split(/\s+/)
+    .filter(Boolean)
     .map((tuple) => {
       const parts = tuple.split(",").map(Number);
       return {
@@ -71,6 +107,664 @@ function parseTriples(s: string): Triple[] {
     });
 }
 
+function cleanLine(points: readonly EnuPoint[]): EnuPoint[] {
+  const clean: EnuPoint[] = [];
+  for (const point of points) {
+    const previous = clean.at(-1);
+    if (previous && Math.hypot(point[0] - previous[0], point[1] - previous[1]) < POINT_EPS_M)
+      continue;
+    clean.push([point[0], point[1]]);
+  }
+  return clean;
+}
+
+function lineLength(points: readonly EnuPoint[]): number {
+  let total = 0;
+  for (let index = 1; index < points.length; index++) {
+    total += Math.hypot(
+      points[index]![0] - points[index - 1]![0],
+      points[index]![1] - points[index - 1]![1],
+    );
+  }
+  return total;
+}
+
+function localRouteSegments(lines: readonly EnuPoint[][]) {
+  const segments: Array<{
+    kind: "work" | "turn";
+    points: EnuPoint[];
+    photoEnabled: boolean;
+  }> = [];
+  lines.forEach((line, index) => {
+    if (index > 0) {
+      segments.push({
+        kind: "turn",
+        points: [lines[index - 1]!.at(-1)!, line[0]!],
+        photoEnabled: false,
+      });
+    }
+    segments.push({ kind: "work", points: line, photoEnabled: true });
+  });
+  return segments;
+}
+
+function serpentineRouteVariants(lines: readonly EnuPoint[][]): EnuPoint[][][] {
+  const variants: EnuPoint[][][] = [];
+  for (const reverseLineOrder of [false, true]) {
+    const ordered = reverseLineOrder ? [...lines].reverse() : [...lines];
+    for (const reverseFirstLine of [false, true]) {
+      variants.push(
+        ordered.map((line, index) =>
+          index % 2 === Number(reverseFirstLine) ? [...line] : [...line].reverse(),
+        ),
+      );
+    }
+  }
+  return variants;
+}
+
+function localRouteCandidate(
+  lines: EnuPoint[][],
+  centerLine: readonly EnuPoint[],
+  elevationOptimizeEnable: boolean | undefined,
+): LocalRouteCandidate {
+  const segments: LocalRouteSegment[] = localRouteSegments(lines);
+  if (elevationOptimizeEnable) {
+    const normalEnd = joinSegmentPoints(segments).at(-1)!;
+    let optimizationLine = [...centerLine];
+    const first = optimizationLine[0]!;
+    const last = optimizationLine.at(-1)!;
+    if (
+      Math.hypot(last[0] - normalEnd[0], last[1] - normalEnd[1]) <
+      Math.hypot(first[0] - normalEnd[0], first[1] - normalEnd[1])
+    ) {
+      optimizationLine = optimizationLine.reverse();
+    }
+    const optimizationPath = cleanLine([normalEnd, ...optimizationLine]);
+    segments.push({
+      kind: "elevationOptimize",
+      // Preserve a distinct stop/start waypoint at the same coordinate, as in DJI exports.
+      points: [normalEnd, ...optimizationPath],
+      photoEnabled: true,
+    });
+  }
+  const executable = joinSegmentPoints(segments);
+  return {
+    lines,
+    segments,
+    start: executable[0]!,
+    end: executable.at(-1)!,
+  };
+}
+
+function shortestCandidateIndexes(
+  candidateGroups: readonly LocalRouteCandidate[][],
+  startPoint: EnuPoint | undefined,
+): number[] {
+  if (candidateGroups.length === 0) return [];
+  let costs = candidateGroups[0]!.map((candidate) =>
+    startPoint
+      ? Math.hypot(candidate.start[0] - startPoint[0], candidate.start[1] - startPoint[1])
+      : 0,
+  );
+  const previousIndexes: number[][] = [candidateGroups[0]!.map(() => -1)];
+
+  for (let regionIndex = 1; regionIndex < candidateGroups.length; regionIndex++) {
+    const previousCandidates = candidateGroups[regionIndex - 1]!;
+    const candidates = candidateGroups[regionIndex]!;
+    const nextCosts: number[] = [];
+    const nextPreviousIndexes: number[] = [];
+    for (const candidate of candidates) {
+      let bestCost = Number.POSITIVE_INFINITY;
+      let bestPreviousIndex = 0;
+      previousCandidates.forEach((previous, previousIndex) => {
+        const transition = Math.hypot(
+          candidate.start[0] - previous.end[0],
+          candidate.start[1] - previous.end[1],
+        );
+        const cost = costs[previousIndex]! + transition;
+        if (cost < bestCost) {
+          bestCost = cost;
+          bestPreviousIndex = previousIndex;
+        }
+      });
+      nextCosts.push(bestCost);
+      nextPreviousIndexes.push(bestPreviousIndex);
+    }
+    costs = nextCosts;
+    previousIndexes.push(nextPreviousIndexes);
+  }
+
+  let selectedIndex = costs.reduce((best, cost, index) => (cost < costs[best]! ? index : best), 0);
+  const selected = Array.from({ length: candidateGroups.length }, () => 0);
+  for (let regionIndex = candidateGroups.length - 1; regionIndex >= 0; regionIndex--) {
+    selected[regionIndex] = selectedIndex;
+    selectedIndex = previousIndexes[regionIndex]![selectedIndex]!;
+  }
+  return selected;
+}
+
+function joinSegmentPoints<T>(segments: readonly { points: readonly T[] }[]): T[] {
+  const result: T[] = [];
+  for (const segment of segments) {
+    if (result.length === 0) result.push(...segment.points);
+    else result.push(...segment.points.slice(1));
+  }
+  return result;
+}
+
+function splitLineByDistance(points: readonly EnuPoint[], distance: number): LocalRegion[] {
+  const total = lineLength(points);
+  const cut = Number.isFinite(distance) && distance > POINT_EPS_M ? distance : total;
+  if (cut >= total - POINT_EPS_M) {
+    return [
+      {
+        id: "region-0",
+        sourceRegionIndexes: [0],
+        startDistance: 0,
+        endDistance: total,
+        centerLine: [...points],
+        polygon: [],
+      },
+    ];
+  }
+
+  const regions: LocalRegion[] = [];
+  let current: EnuPoint[] = [points[0]!];
+  let regionStart = 0;
+  let accumulated = 0;
+
+  const finishRegion = (endDistance: number) => {
+    if (current.length < 2) return;
+    regions.push({
+      id: `region-${regions.length}`,
+      sourceRegionIndexes: [regions.length],
+      startDistance: regionStart,
+      endDistance,
+      centerLine: current,
+      polygon: [],
+    });
+    current = [current.at(-1)!];
+    regionStart = endDistance;
+  };
+
+  for (let index = 1; index < points.length; index++) {
+    const a = points[index - 1]!;
+    const b = points[index]!;
+    const segmentLength = Math.hypot(b[0] - a[0], b[1] - a[1]);
+
+    // FlightHub keeps original control points as region boundaries. If the next
+    // complete segment would cross the cutting distance, finish at its starting
+    // control point instead of synthesizing a point in the middle of the segment.
+    const currentLength = accumulated - regionStart;
+    if (currentLength > POINT_EPS_M && currentLength + segmentLength > cut + POINT_EPS_M) {
+      finishRegion(accumulated);
+    }
+
+    // A single source segment can itself exceed the limit; only that case needs
+    // synthetic points so every generated region remains bounded by `cut`.
+    let segmentStart = a;
+    let consumed = 0;
+    while (segmentLength - consumed > cut + POINT_EPS_M) {
+      const step = cut;
+      const t = (consumed + step) / segmentLength;
+      const point: EnuPoint = [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+      if (current.at(-1) !== segmentStart) current.push(segmentStart);
+      current.push(point);
+      finishRegion(accumulated + consumed + step);
+      segmentStart = point;
+      consumed += step;
+    }
+    if (current.at(-1) !== segmentStart) current.push(segmentStart);
+    current.push(b);
+    accumulated += segmentLength;
+  }
+  finishRegion(total);
+  return regions;
+}
+
+function applyMergedRegionRanges(
+  regions: readonly LocalRegion[],
+  ranges: readonly number[][] | undefined,
+): LocalRegion[] {
+  if (!ranges || ranges.length === 0) return [...regions];
+  const normalized = ranges
+    .map((range) => {
+      if (range.length !== 2) {
+        throw new PlannerError("mappingStrip merged region range must contain [start,end]");
+      }
+      const start = range[0]! - 1;
+      const end = range[1]! - 1;
+      if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start) {
+        throw new PlannerError("mappingStrip merged region range is invalid");
+      }
+      if (end >= regions.length) {
+        throw new PlannerError("mappingStrip merged region range exceeds region count");
+      }
+      return { start, end };
+    })
+    .sort((a, b) => a.start - b.start);
+  for (let index = 1; index < normalized.length; index++) {
+    if (normalized[index]!.start <= normalized[index - 1]!.end) {
+      throw new PlannerError("mappingStrip merged region ranges cannot overlap");
+    }
+  }
+
+  const byStart = new Map(normalized.map((range) => [range.start, range]));
+  const merged: LocalRegion[] = [];
+  for (let index = 0; index < regions.length; ) {
+    const range = byStart.get(index);
+    if (!range) {
+      merged.push(regions[index]!);
+      index += 1;
+      continue;
+    }
+    const members = regions.slice(range.start, range.end + 1);
+    merged.push({
+      id: `region-${range.start}-${range.end}`,
+      sourceRegionIndexes: members.flatMap((region) => region.sourceRegionIndexes),
+      startDistance: members[0]!.startDistance,
+      endDistance: members.at(-1)!.endDistance,
+      centerLine: members.flatMap((region, memberIndex) =>
+        memberIndex === 0 ? region.centerLine : region.centerLine.slice(1),
+      ),
+      polygon: [],
+      beforePoint: members[0]!.beforePoint,
+      afterPoint: members.at(-1)!.afterPoint,
+    });
+    index = range.end + 1;
+  }
+  return merged;
+}
+
+function cross(a: EnuPoint, b: EnuPoint): number {
+  return a[0] * b[1] - a[1] * b[0];
+}
+
+function segmentUnit(a: EnuPoint, b: EnuPoint): EnuPoint {
+  const length = Math.hypot(b[0] - a[0], b[1] - a[1]);
+  if (length < POINT_EPS_M) throw new PlannerError("mappingStrip center line has a zero segment");
+  return [(b[0] - a[0]) / length, (b[1] - a[1]) / length];
+}
+
+function leftNormal(direction: EnuPoint): EnuPoint {
+  return [-direction[1], direction[0]];
+}
+
+function offsetPolyline(points: readonly EnuPoint[], distance: number): EnuPoint[] {
+  if (distance === 0) return points.map((point) => [point[0], point[1]]);
+  const directions = points.slice(1).map((point, index) => segmentUnit(points[index]!, point));
+  const out: EnuPoint[] = [];
+  const firstNormal = leftNormal(directions[0]!);
+  out.push([points[0]![0] + firstNormal[0] * distance, points[0]![1] + firstNormal[1] * distance]);
+
+  for (let index = 1; index < points.length - 1; index++) {
+    const previousDirection = directions[index - 1]!;
+    const nextDirection = directions[index]!;
+    const previousNormal = leftNormal(previousDirection);
+    const nextNormal = leftNormal(nextDirection);
+    const previousOffset: EnuPoint = [
+      points[index]![0] + previousNormal[0] * distance,
+      points[index]![1] + previousNormal[1] * distance,
+    ];
+    const nextOffset: EnuPoint = [
+      points[index]![0] + nextNormal[0] * distance,
+      points[index]![1] + nextNormal[1] * distance,
+    ];
+    const denominator = cross(previousDirection, nextDirection);
+    if (Math.abs(denominator) < 1e-9) {
+      out.push(previousOffset);
+      continue;
+    }
+    const delta: EnuPoint = [nextOffset[0] - previousOffset[0], nextOffset[1] - previousOffset[1]];
+    const t = cross(delta, nextDirection) / denominator;
+    const intersection: EnuPoint = [
+      previousOffset[0] + previousDirection[0] * t,
+      previousOffset[1] + previousDirection[1] * t,
+    ];
+    const miterLength = Math.hypot(
+      intersection[0] - points[index]![0],
+      intersection[1] - points[index]![1],
+    );
+    if (miterLength <= Math.abs(distance) * MITER_LIMIT) out.push(intersection);
+    else out.push(previousOffset, nextOffset);
+  }
+
+  const lastNormal = leftNormal(directions.at(-1)!);
+  const last = points.at(-1)!;
+  out.push([last[0] + lastNormal[0] * distance, last[1] + lastNormal[1] * distance]);
+  return out;
+}
+
+function corridorSide(
+  points: readonly EnuPoint[],
+  distance: number,
+  beforePoint?: EnuPoint,
+  afterPoint?: EnuPoint,
+): EnuPoint[] {
+  const out: EnuPoint[] = [];
+  for (let index = 0; index < points.length; index++) {
+    const point = points[index]!;
+    const previous = index > 0 ? points[index - 1] : beforePoint;
+    const next = index + 1 < points.length ? points[index + 1] : afterPoint;
+    if (!previous && next) {
+      const normal = leftNormal(segmentUnit(point, next));
+      out.push([point[0] + normal[0] * distance, point[1] + normal[1] * distance]);
+      continue;
+    }
+    if (previous && !next) {
+      const normal = leftNormal(segmentUnit(previous, point));
+      out.push([point[0] + normal[0] * distance, point[1] + normal[1] * distance]);
+      continue;
+    }
+    if (!previous || !next) continue;
+
+    const previousDirection = segmentUnit(previous, point);
+    const nextDirection = segmentUnit(point, next);
+    const previousNormal = leftNormal(previousDirection);
+    const nextNormal = leftNormal(nextDirection);
+    const previousOffset: EnuPoint = [
+      point[0] + previousNormal[0] * distance,
+      point[1] + previousNormal[1] * distance,
+    ];
+    const nextOffset: EnuPoint = [
+      point[0] + nextNormal[0] * distance,
+      point[1] + nextNormal[1] * distance,
+    ];
+    const denominator = cross(previousDirection, nextDirection);
+    if (Math.abs(denominator) < 1e-9) {
+      out.push(previousOffset);
+      continue;
+    }
+
+    // FlightHub uses a bevel on the outside of every bend. The inside remains
+    // a miter intersection so the corridor does not overlap itself at corners.
+    if (denominator * distance < 0) {
+      out.push(previousOffset, nextOffset);
+      continue;
+    }
+    const delta: EnuPoint = [nextOffset[0] - previousOffset[0], nextOffset[1] - previousOffset[1]];
+    const t = cross(delta, nextDirection) / denominator;
+    const intersection: EnuPoint = [
+      previousOffset[0] + previousDirection[0] * t,
+      previousOffset[1] + previousDirection[1] * t,
+    ];
+    const miterLength = Math.hypot(intersection[0] - point[0], intersection[1] - point[1]);
+    if (miterLength <= Math.abs(distance) * MITER_LIMIT) out.push(intersection);
+    else out.push(previousOffset, nextOffset);
+  }
+  return out;
+}
+
+function corridorPolygon(
+  points: readonly EnuPoint[],
+  left: number,
+  right: number,
+  beforePoint?: EnuPoint,
+  afterPoint?: EnuPoint,
+): EnuPoint[] {
+  return [
+    ...corridorSide(points, left, beforePoint, afterPoint),
+    ...corridorSide(points, -right, beforePoint, afterPoint).reverse(),
+  ];
+}
+
+function perpendicularRouteLines(
+  centerLine: readonly EnuPoint[],
+  leftExtend: number,
+  rightExtend: number,
+  margin: number,
+  lineSpacing: number,
+): EnuPoint[][] {
+  const left = offsetPolyline(centerLine, leftExtend);
+  const right = offsetPolyline(centerLine, -rightExtend);
+  if (left.length !== centerLine.length || right.length !== centerLine.length) {
+    throw new PlannerError("mappingStrip offset corridor cannot be segmented");
+  }
+
+  const lines: EnuPoint[][] = [];
+  for (let index = 0; index < centerLine.length - 1; index++) {
+    const segment = [centerLine[index]!, centerLine[index + 1]!] as const;
+    const cell = [left[index]!, left[index + 1]!, right[index + 1]!, right[index]!];
+    const direction = segmentUnit(segment[0], segment[1]);
+    const projections = cell.map((point) => point[0] * direction[0] + point[1] * direction[1]);
+    const longitudinalSpan = Math.max(...projections) - Math.min(...projections);
+    const sourceSegmentLength = lineLength(segment);
+    const previousDirection =
+      index > 0 ? segmentUnit(centerLine[index - 1]!, segment[0]) : undefined;
+    const hasSharpStart =
+      previousDirection !== undefined &&
+      Math.abs(cross(previousDirection, direction)) > Math.sin((5 * Math.PI) / 180);
+    const lineCount = Math.max(
+      1,
+      Math.ceil(sourceSegmentLength / lineSpacing),
+      hasSharpStart
+        ? Math.ceil(longitudinalSpan / lineSpacing)
+        : Math.round(longitudinalSpan / lineSpacing),
+    );
+    const phaseOffset = Math.max(0, (longitudinalSpan - (lineCount - 1) * lineSpacing) / 2);
+    const grid = surveyGrid(cell, {
+      directionDeg: (bearingDeg(segment[0], segment[1]) + 90) % 360,
+      marginM: margin,
+      lineSpacing,
+      phaseOffsetM: phaseOffset,
+    });
+    const flightDirection: EnuPoint = [direction[1], -direction[0]];
+    for (let gridIndex = 0; gridIndex + 1 < grid.length; gridIndex += 2) {
+      const a = grid[gridIndex]!;
+      const b = grid[gridIndex + 1]!;
+      const followsDirection =
+        (b[0] - a[0]) * flightDirection[0] + (b[1] - a[1]) * flightDirection[1] >= 0;
+      lines.push(followsDirection ? [a, b] : [b, a]);
+    }
+  }
+  return lines;
+}
+
+function polygonArea(points: readonly EnuPoint[]): number {
+  let area2 = 0;
+  for (let index = 0; index < points.length; index++) {
+    const a = points[index]!;
+    const b = points[(index + 1) % points.length]!;
+    area2 += a[0] * b[1] - b[0] * a[1];
+  }
+  return Math.abs(area2) / 2;
+}
+
+function routeOffsets(folder: MappingStripFolder, inputs: StripPlanInputs): number[] {
+  if (folder.Placemark.singleLineEnable) return [0];
+  const left = folder.Placemark.leftExtend;
+  const right = folder.Placemark.rightExtend;
+  const minimum = -right;
+  const maximum = left;
+  const spacing = inputs.lineSpacing;
+  if (!(spacing > POINT_EPS_M && Number.isFinite(spacing)))
+    throw new PlannerError("mappingStrip lineSpacing must be finite and greater than zero");
+
+  const span = maximum - minimum;
+  const hasInfrared = folder.payloadParam?.imageFormat?.includes("ir") ?? false;
+  const minimumCount = Math.max(
+    hasInfrared && span > spacing + POINT_EPS_M ? 2 : 1,
+    Math.ceil(Math.max(0, span - inputs.crossTrackFootprint) / spacing) + 1,
+  );
+  if (minimumCount === 1) return [0];
+  const count =
+    minimumCount % 2 === 0
+      ? minimumCount
+      : folder.Placemark.includeCenterEnable
+        ? minimumCount
+        : minimumCount + 1;
+  if (count > MAX_ROUTE_COUNT) throw new PlannerError("mappingStrip route count exceeds limit");
+  const offsets = Array.from(
+    { length: count },
+    (_, index) => (minimum + maximum - (count - 1) * spacing) / 2 + index * spacing,
+  );
+  if (folder.Placemark.includeCenterEnable) {
+    const oddCount = minimumCount % 2 === 1 ? minimumCount : minimumCount + 1;
+    const centered = Array.from(
+      { length: oddCount },
+      (_, index) => (index - (oddCount - 1) / 2) * spacing,
+    );
+    if (centered[0]! >= minimum && centered.at(-1)! <= maximum) return centered;
+    if (!offsets.some((offset) => Math.abs(offset) < POINT_EPS_M)) offsets.push(0);
+  }
+  return offsets.sort((a, b) => a - b);
+}
+
+function normalizeInputs(folder: MappingStripFolder, options?: PlanOptions): StripPlanInputs {
+  const corridorWidth = folder.Placemark.leftExtend + folder.Placemark.rightExtend;
+  return {
+    crossTrackFootprint: Number(options?.crossTrackFootprint ?? corridorWidth),
+    lineSpacing: Number(options?.lineSpacing ?? Math.max(corridorWidth, 1)),
+    photoSpacing: Number(options?.photoSpacing ?? 1),
+    shootInterval: Number(options?.shootInterval ?? 1),
+  };
+}
+
+export function deriveMappingStrip(
+  template: MappingStripTemplate,
+  options?: PlanOptions,
+): MappingStripDerived {
+  const folder = template.Folder;
+  if (folder.Placemark.leftExtend < 0 || folder.Placemark.rightExtend < 0)
+    throw new PlannerError("mappingStrip extend distances cannot be negative");
+  const triples = parseTriples(folder.Placemark.LineString.coordinates);
+  if (triples.length < 2)
+    throw new PlannerError("mappingStrip requires at least two center points");
+  if (triples.some((point) => !Number.isFinite(point.lng) || !Number.isFinite(point.lat)))
+    throw new PlannerError("mappingStrip center line contains non-finite coordinates");
+
+  const origin = centroid(triples);
+  const centerLine = cleanLine(triples.map((point) => lngLatToEnu(point, origin)));
+  if (centerLine.length < 2)
+    throw new PlannerError("mappingStrip requires two distinct center points");
+  const inputs = normalizeInputs(folder, options);
+  if (!(inputs.crossTrackFootprint > 0 && Number.isFinite(inputs.crossTrackFootprint)))
+    throw new PlannerError("mappingStrip crossTrackFootprint must be finite and greater than zero");
+  if (!(inputs.photoSpacing > 0 && Number.isFinite(inputs.photoSpacing)))
+    throw new PlannerError("mappingStrip photoSpacing must be finite and greater than zero");
+
+  const splitRegions = splitLineByDistance(centerLine, folder.Placemark.cuttingDistance);
+  const contextualRegions = splitRegions.map((region, index) => ({
+    ...region,
+    beforePoint: index > 0 ? splitRegions[index - 1]!.centerLine.at(-2) : undefined,
+    afterPoint:
+      index + 1 < splitRegions.length ? splitRegions[index + 1]!.centerLine[1] : undefined,
+  }));
+  const localRegions = applyMergedRegionRanges(
+    contextualRegions,
+    folder.Placemark.stripMergedRegions,
+  ).map((region) => ({
+    ...region,
+    polygon: corridorPolygon(
+      region.centerLine,
+      folder.Placemark.leftExtend,
+      folder.Placemark.rightExtend,
+      region.beforePoint,
+      region.afterPoint,
+    ),
+  }));
+  const offsets = routeOffsets(folder, inputs);
+  const executionRegions = options?.regionOrderReversed
+    ? [...localRegions].reverse()
+    : localRegions;
+  const perpendicular =
+    options?.stripDirection === "perpendicular" && !folder.Placemark.singleLineEnable;
+  const candidateGroups = executionRegions.map((region) => {
+    const rawLines = perpendicular
+      ? perpendicularRouteLines(
+          region.centerLine,
+          folder.Placemark.leftExtend,
+          folder.Placemark.rightExtend,
+          folder.Placemark.margin,
+          inputs.lineSpacing,
+        )
+      : offsets.map((offset) => offsetPolyline(region.centerLine, offset));
+    if (rawLines.length === 0)
+      throw new PlannerError("mappingStrip region has no available flight routes");
+    return serpentineRouteVariants(rawLines).map((lines) =>
+      localRouteCandidate(lines, region.centerLine, folder.Placemark.elevationOptimizeEnable),
+    );
+  });
+  const takeOffRefPoint = template.missionConfig.takeOffRefPoint;
+  const selectedCandidateIndexes = shortestCandidateIndexes(
+    candidateGroups,
+    takeOffRefPoint ? lngLatToEnu(takeOffRefPoint, origin) : undefined,
+  );
+  const flightRoutes: MappingStripRegionRoute[] = [];
+  let previousRegionEnd: EnuPoint | undefined;
+  executionRegions.forEach((region, regionIndex) => {
+    const candidate = candidateGroups[regionIndex]![selectedCandidateIndexes[regionIndex]!]!;
+    const localSegments: Array<{
+      kind: "work" | "turn" | "transit" | "elevationOptimize";
+      points: EnuPoint[];
+      photoEnabled: boolean;
+    }> = previousRegionEnd
+      ? [
+          {
+            kind: "transit",
+            points: [previousRegionEnd, candidate.start],
+            photoEnabled: false,
+          },
+          ...candidate.segments,
+        ]
+      : candidate.segments;
+    const displayPath = joinSegmentPoints(localSegments);
+    const executable = joinSegmentPoints(candidate.segments);
+    flightRoutes.push({
+      regionId: region.id,
+      routeOffsets: perpendicular ? [] : offsets.map(meters),
+      routeLines: candidate.lines.map((line) => line.map((point) => enuToLngLat(point, origin))),
+      segments: localSegments.map((segment) => ({
+        ...segment,
+        points: segment.points.map((point) => enuToLngLat(point, origin)),
+      })),
+      executablePath: executable.map((point) => enuToLngLat(point, origin)),
+      length: meters(lineLength(displayPath)),
+    });
+    previousRegionEnd = candidate.end;
+  });
+
+  const surveyAreaLocal = corridorPolygon(
+    centerLine,
+    folder.Placemark.leftExtend,
+    folder.Placemark.rightExtend,
+  );
+  const totalFlightLength = flightRoutes.reduce((sum, route) => sum + Number(route.length), 0);
+  const estimatedPhotoCount = flightRoutes.reduce(
+    (sum, route) =>
+      sum +
+      route.segments
+        .filter(({ photoEnabled }) => photoEnabled)
+        .reduce((lineSum, segment) => {
+          let length = 0;
+          for (let index = 1; index < segment.points.length; index++)
+            length += haversineMeters(segment.points[index - 1]!, segment.points[index]!);
+          return lineSum + Math.max(1, Math.floor(length / inputs.photoSpacing) + 1);
+        }, 0),
+    0,
+  );
+
+  return {
+    centerLineLength: meters(lineLength(centerLine)),
+    surveyArea: surveyAreaLocal.map((point) => enuToLngLat(point, origin)),
+    surveyAreaSize: localRegions.reduce((sum, region) => sum + polygonArea(region.polygon), 0),
+    regions: localRegions.map((region) => ({
+      id: region.id,
+      sourceRegionIndexes: region.sourceRegionIndexes,
+      startDistance: meters(region.startDistance),
+      endDistance: meters(region.endDistance),
+      centerLine: region.centerLine.map((point) => enuToLngLat(point, origin)),
+      polygon: region.polygon.map((point) => enuToLngLat(point, origin)),
+    })),
+    flightRoutes,
+    totalFlightLength: meters(totalFlightLength),
+    photoSpacing: meters(inputs.photoSpacing),
+    estimatedPhotoCount,
+    estimatedDuration: totalFlightLength / Number(folder.autoFlightSpeed),
+  };
+}
+
 function heightModeToExecuteMode(folder: MappingStripFolder): ExecuteHeightMode {
   switch (folder.waylineCoordinateSysParam.heightMode) {
     case "EGM96":
@@ -82,3 +776,317 @@ function heightModeToExecuteMode(folder: MappingStripFolder): ExecuteHeightMode
       return "realTimeFollowSurface";
   }
 }
+
+function turnDamping(points: readonly LngLat[], index: number): Meters {
+  const previous = haversineMeters(points[index - 1]!, points[index]!);
+  const next = haversineMeters(points[index]!, points[index + 1]!);
+  return meters(Math.min(TURN_DAMPING_M, previous * 0.45, next * 0.45));
+}
+
+function shootingGroups(
+  folder: MappingStripFolder,
+  startIndex: number,
+  endIndex: number,
+  firstGroupId: number,
+  inputs: StripPlanInputs,
+): ActionGroup[] {
+  const lenses: LensType[] = folder.payloadParam?.imageFormat ?? ["visable"];
+  if (folder.Placemark.shootType === "time") {
+    return [
+      {
+        actionGroupId: firstGroupId,
+        actionGroupStartIndex: startIndex,
+        actionGroupEndIndex: endIndex,
+        actionGroupMode: "sequence",
+        actionTrigger: { actionTriggerType: "betweenAdjacentPoints" },
+        action: [
+          {
+            actionId: 0,
+            actionActuatorFunc: "startTimeLapse",
+            actionActuatorFuncParam: {
+              payloadPositionIndex: folder.payloadParam?.payloadPositionIndex ?? 0,
+              useGlobalPayloadLensIndex: false,
+              payloadLensIndex: lenses,
+              minShootInterval: inputs.shootInterval,
+            },
+          },
+        ],
+      },
+      {
+        actionGroupId: firstGroupId + 1,
+        actionGroupStartIndex: endIndex,
+        actionGroupEndIndex: endIndex,
+        actionGroupMode: "sequence",
+        actionTrigger: { actionTriggerType: "reachPoint" },
+        action: [
+          {
+            actionId: 0,
+            actionActuatorFunc: "stopTimeLapse",
+            actionActuatorFuncParam: {
+              payloadPositionIndex: folder.payloadParam?.payloadPositionIndex ?? 0,
+              payloadLensIndex: lenses,
+            },
+          },
+        ],
+      },
+    ];
+  }
+  return [
+    {
+      actionGroupId: firstGroupId,
+      actionGroupStartIndex: startIndex,
+      actionGroupEndIndex: endIndex,
+      actionGroupMode: "sequence",
+      actionTrigger: {
+        actionTriggerType: "multipleDistance",
+        actionTriggerParam: inputs.photoSpacing,
+      },
+      action: [
+        {
+          actionId: 0,
+          actionActuatorFunc: "takePhoto",
+          actionActuatorFuncParam: {
+            payloadPositionIndex: folder.payloadParam?.payloadPositionIndex ?? 0,
+            useGlobalPayloadLensIndex: false,
+            payloadLensIndex: lenses,
+          },
+        },
+      ],
+    },
+  ];
+}
+
+function nadirGimbalRotateAction(folder: MappingStripFolder, actionId: number) {
+  return {
+    actionId,
+    actionActuatorFunc: "gimbalRotate" as const,
+    actionActuatorFuncParam: {
+      payloadPositionIndex: folder.payloadParam?.payloadPositionIndex ?? 0,
+      gimbalHeadingYawBase: "aircraft" as const,
+      gimbalRotateMode: "absoluteAngle" as const,
+      gimbalPitchRotateEnable: true,
+      gimbalPitchRotateAngle: degrees(-90),
+      gimbalRollRotateEnable: false,
+      gimbalRollRotateAngle: degrees(0),
+      gimbalYawRotateEnable: false,
+      gimbalYawRotateAngle: degrees(0),
+      gimbalRotateTimeEnable: false,
+      gimbalRotateTime: 10,
+    },
+  };
+}
+
+function continuousMappingGroups(
+  folder: MappingStripFolder,
+  endIndex: number,
+  inputs: StripPlanInputs,
+): ActionGroup[] {
+  const payloadPositionIndex = folder.payloadParam?.payloadPositionIndex ?? 0;
+  const lenses: LensType[] = folder.payloadParam?.imageFormat ?? ["visable"];
+  const startAction =
+    folder.Placemark.shootType === "time"
+      ? {
+          actionId: 2,
+          actionActuatorFunc: "startTimeLapse" as const,
+          actionActuatorFuncParam: {
+            payloadPositionIndex,
+            useGlobalPayloadLensIndex: false,
+            payloadLensIndex: lenses,
+            minShootInterval: inputs.shootInterval,
+          },
+        }
+      : {
+          actionId: 2,
+          actionActuatorFunc: "takePhoto" as const,
+          actionActuatorFuncParam: {
+            payloadPositionIndex,
+            useGlobalPayloadLensIndex: false,
+            payloadLensIndex: lenses,
+          },
+        };
+  return [
+    {
+      actionGroupId: 0,
+      actionGroupStartIndex: 0,
+      actionGroupEndIndex: endIndex,
+      actionGroupMode: "sequence",
+      actionTrigger: { actionTriggerType: "betweenAdjacentPoints" },
+      action: [
+        {
+          actionId: 0,
+          actionActuatorFunc: "gimbalAngleLock",
+          actionActuatorFuncParam: { payloadPositionIndex },
+        },
+        nadirGimbalRotateAction(folder, 1),
+        startAction,
+      ],
+    },
+    {
+      actionGroupId: 1,
+      actionGroupStartIndex: 0,
+      actionGroupEndIndex: endIndex,
+      actionGroupMode: "sequence",
+      actionTrigger: { actionTriggerType: "multipleTiming", actionTriggerParam: 2 },
+      action: [nadirGimbalRotateAction(folder, 0)],
+    },
+    {
+      actionGroupId: 2,
+      actionGroupStartIndex: endIndex,
+      actionGroupEndIndex: endIndex,
+      actionGroupMode: "sequence",
+      actionTrigger: { actionTriggerType: "reachPoint" },
+      action: [
+        ...(folder.Placemark.shootType === "time"
+          ? [
+              {
+                actionId: 0,
+                actionActuatorFunc: "stopTimeLapse" as const,
+                actionActuatorFuncParam: { payloadPositionIndex, payloadLensIndex: lenses },
+              },
+            ]
+          : []),
+        { actionId: 1, actionActuatorFunc: "gimbalAngleUnlock" as const },
+      ],
+    },
+  ];
+}
+
+function elevationOptimizeGroups(
+  folder: MappingStripFolder,
+  startIndex: number,
+  endIndex: number,
+  firstGroupId: number,
+  inputs: StripPlanInputs,
+): ActionGroup[] {
+  const payloadPositionIndex = folder.payloadParam?.payloadPositionIndex ?? 0;
+  const gimbalGroup: ActionGroup = {
+    actionGroupId: firstGroupId,
+    actionGroupStartIndex: startIndex,
+    actionGroupEndIndex: startIndex,
+    actionGroupMode: "sequence",
+    actionTrigger: { actionTriggerType: "reachPoint" },
+    action: [
+      {
+        actionId: 0,
+        actionActuatorFunc: "gimbalRotate",
+        actionActuatorFuncParam: {
+          payloadPositionIndex,
+          gimbalHeadingYawBase: "aircraft",
+          gimbalRotateMode: "absoluteAngle",
+          gimbalPitchRotateEnable: true,
+          gimbalPitchRotateAngle: degrees(-45),
+          gimbalRollRotateEnable: false,
+          gimbalRollRotateAngle: degrees(0),
+          gimbalYawRotateEnable: true,
+          gimbalYawRotateAngle: degrees(0),
+          gimbalRotateTimeEnable: false,
+          gimbalRotateTime: 10,
+        },
+      },
+      {
+        actionId: 1,
+        actionActuatorFunc: "hover",
+        actionActuatorFuncParam: { hoverTime: 0.5 },
+      },
+    ],
+  };
+  const shooting = shootingGroups(folder, startIndex, endIndex, firstGroupId + 1, inputs);
+  const unlockGroup: ActionGroup = {
+    actionGroupId: firstGroupId + shooting.length + 1,
+    actionGroupStartIndex: endIndex,
+    actionGroupEndIndex: endIndex,
+    actionGroupMode: "sequence",
+    actionTrigger: { actionTriggerType: "reachPoint" },
+    action: [{ actionId: 0, actionActuatorFunc: "gimbalAngleUnlock" }],
+  };
+  return [gimbalGroup, ...shooting, unlockGroup];
+}
+
+/** Compile a mappingStrip template into one executable Folder per cut region. */
+export function planMappingStrip(template: MappingStripTemplate, options?: PlanOptions): Waylines {
+  const folder = template.Folder;
+  const derived = deriveMappingStrip(template, options);
+  const inputs = normalizeInputs(folder, options);
+  const waylineFolders: WaylinesFolder[] = derived.flightRoutes.map((route, waylineId) => {
+    const points = route.executablePath;
+    const groupsByStart = new Map<number, ActionGroup[]>();
+    const forcedStopIndexes = new Set<number>();
+    if (!folder.Placemark.elevationOptimizeEnable) {
+      for (const group of continuousMappingGroups(folder, points.length - 1, inputs)) {
+        const index = group.actionGroupStartIndex;
+        groupsByStart.set(index, [...(groupsByStart.get(index) ?? []), group]);
+      }
+    } else {
+      let cursor = 0;
+      let nextActionGroupId = 0;
+      for (const segment of route.segments.filter(({ kind }) => kind !== "transit")) {
+        const startIndex = cursor;
+        const endIndex = startIndex + segment.points.length - 1;
+        if (segment.photoEnabled && endIndex > startIndex) {
+          const shootingStartIndex =
+            segment.kind === "elevationOptimize" ? startIndex + 1 : startIndex;
+          const groups =
+            segment.kind === "elevationOptimize"
+              ? elevationOptimizeGroups(
+                  folder,
+                  shootingStartIndex,
+                  endIndex,
+                  nextActionGroupId,
+                  inputs,
+                )
+              : shootingGroups(folder, shootingStartIndex, endIndex, nextActionGroupId, inputs);
+          nextActionGroupId += groups.length;
+          for (const group of groups) {
+            const index = group.actionGroupStartIndex;
+            groupsByStart.set(index, [...(groupsByStart.get(index) ?? []), group]);
+          }
+          if (segment.kind === "elevationOptimize") {
+            forcedStopIndexes.add(startIndex);
+            forcedStopIndexes.add(shootingStartIndex);
+            forcedStopIndexes.add(endIndex);
+          }
+        }
+        cursor = endIndex;
+      }
+    }
+    const placemarks: WaylinesPlacemark[] = points.map((point, index) => {
+      const isFirst = index === 0;
+      const isLast = index === points.length - 1;
+      const headingAngle = isLast
+        ? 0
+        : bearingDeg(lngLatToEnu(point, point), lngLatToEnu(points[index + 1]!, point));
+      return {
+        Point: { coordinates: point },
+        index,
+        executeHeight: folder.Placemark.height,
+        waypointSpeed: folder.autoFlightSpeed,
+        waypointHeadingParam: {
+          waypointHeadingMode: "followWayline",
+          waypointHeadingAngle: degrees(headingAngle),
+          waypointHeadingPathMode: "followBadArc",
+        },
+        waypointTurnParam:
+          isFirst || isLast || forcedStopIndexes.has(index)
+            ? {
+                waypointTurnMode: "toPointAndStopWithDiscontinuityCurvature",
+                waypointTurnDampingDist: meters(0),
+              }
+            : {
+                waypointTurnMode: "coordinateTurn",
+                waypointTurnDampingDist: turnDamping(points, index),
+              },
+        useStraightLine: true,
+        isRisky: false,
+        ...(groupsByStart.has(index) ? { actionGroup: groupsByStart.get(index) } : {}),
+      };
+    });
+    return {
+      templateId: folder.templateId + waylineId,
+      waylineId,
+      executeHeightMode: heightModeToExecuteMode(folder),
+      autoFlightSpeed: folder.autoFlightSpeed,
+      Placemark: placemarks,
+    };
+  });
+  return { missionConfig: template.missionConfig, Folder: waylineFolders };
+}