@lumikmz/kmz 0.2.1 → 0.3.0

package/src/plan/plan-mapping2d.ts

@@ -1,128 +1,551 @@
-import { degrees, metersPerSecond } from "../types/branded.js";
-import type { ActionGroup } from "../types/action.js";
+import { degrees, meters, type Meters } from "../types/branded.js";
+import type { Action } from "../types/action.js";
 import type { ExecuteHeightMode } from "../types/enums.js";
-import type { Mapping2dTemplate, Mapping2dFolder } from "../types/template.js";
+import type { Mapping2dFolder, Mapping2dTemplate } from "../types/template.js";
+import type { StartActionGroup } from "../types/waylines.js";
 import type { Waylines, WaylinesFolder } from "../types/waylines.js";
 import type { WaylinesPlacemark } from "../types/placemark.js";
+import { PlannerError } from "../types/errors.js";
 import {
   bearingDeg,
   centroid,
   enuToLngLat,
+  type EnuPoint,
   lngLatToEnu,
+  offsetPolygon,
+  orientPathToHome,
   parseCoordinatesString,
-  scanWaypoints,
+  surveyGrid,
 } from "./geometry.js";
+import type { PlanOptions } from "./index.js";
 
-/** Default HFOV (degrees) used to estimate ground footprint when payload-specific FOV unknown. */
-const DEFAULT_HFOV_DEG = 84;
-
-export function planMapping2d(template: Mapping2dTemplate): Waylines {
+/**
+ * `standoffM` dilates the survey polygon outward before gridding (smart-oblique
+ * needs the grid to overfly the boundary on every side; 0 for ortho/quick-ortho).
+ */
+function buildGrid(template: Mapping2dTemplate, lineSpacing: number, standoffM = 0) {
   const folder = template.Folder;
   const ring = parseCoordinatesString(
     folder.Placemark.Polygon.outerBoundaryIs.LinearRing.coordinates,
   );
   const origin = centroid(ring);
-  const enuPolygon = ring.map((p) => lngLatToEnu(p, origin));
+  const enuRing = ring.map((p) => lngLatToEnu(p, origin));
+  const gridRing = standoffM > 0 ? offsetPolygon(enuRing, standoffM) : enuRing;
+  const enuWps = orientPathToHome(
+    surveyGrid(gridRing, {
+      directionDeg: folder.Placemark.direction,
+      marginM: folder.Placemark.margin,
+      lineSpacing,
+    }),
+    origin,
+    template.missionConfig.takeOffRefPoint,
+  );
+  return { folder, origin, enuWps };
+}
 
-  const hfovRad = (DEFAULT_HFOV_DEG / 2) * (Math.PI / 180);
-  const footprintWidth = 2 * folder.height * Math.tan(hfovRad);
-  const sideOverlap = folder.overlap.orthoCameraOverlapW ?? 70;
-  const lineSpacing = footprintWidth * (1 - sideOverlap / 100);
+/**
+ * Smart-oblique stand-off (meters). The gimbal swings up to |swing|° off nadir in
+ * all directions during a single pass, so the most-oblique look images h·tan(|swing|)
+ * away from the aircraft. The survey polygon is therefore dilated by this distance so
+ * the grid overflies the boundary on every side. Clamp to 3·h.
+ */
+function smartObliqueStandoff(folder: Mapping2dFolder): number {
+  const h = Number(folder.Placemark.height);
+  const swingAbs = Math.abs(Number(folder.Placemark.smartObliqueGimbalPitch ?? degrees(-45)));
+  if (!(swingAbs > 0 && swingAbs < 90)) return 0;
+  return Math.min(h * Math.tan((swingAbs * Math.PI) / 180), h * 3);
+}
 
-  const enuWps = scanWaypoints(enuPolygon, lineSpacing);
-  const lngLatWps = enuWps.map((p) => enuToLngLat(p, origin));
+function heightModeToExecuteMode(folder: Mapping2dFolder): ExecuteHeightMode {
+  switch (folder.waylineCoordinateSysParam.heightMode) {
+    case "EGM96":
+      return "WGS84";
+    case "relativeToStartPoint":
+      return "relativeToStartPoint";
+    case "aboveGroundLevel":
+    case "realTimeFollowSurface":
+      return "realTimeFollowSurface";
+  }
+}
 
-  let actionGroupId = 0;
-  const placemarks: WaylinesPlacemark[] = lngLatWps.map((coord, index) => {
-    const isLast = index === lngLatWps.length - 1;
-    const headingAngle = isLast ? 0 : bearingDeg(enuWps[index]!, enuWps[index + 1]!);
+/** Desired damping distance; clamped down when segments are short. */
+const DESIRED_TURN_DAMPING_M = 10;
 
-    const actionGroup: ActionGroup[] = isLast
-      ? []
-      : [
-          {
-            actionGroupId: actionGroupId++,
-            actionGroupStartIndex: index,
-            actionGroupEndIndex: index + 1,
-            actionGroupMode: "sequence",
-            actionTrigger: { actionTriggerType: "betweenAdjacentPoints" },
-            action: [
-              {
-                actionId: 0,
-                actionActuatorFunc: "takePhoto",
-                actionActuatorFuncParam: {
-                  payloadPositionIndex: 0,
-                  payloadLensIndex: ["wide"],
-                  useGlobalPayloadLensIndex: false,
-                },
-              },
-            ],
-          },
-        ];
+/** Never consume more than this fraction of either adjacent segment. */
+const MAX_DAMPING_FRAC = 0.45;
 
-    return {
+/** Flat ENU distance between two grid points (metres). */
+function enuSegLen(a: EnuPoint, b: EnuPoint): number {
+  return Math.hypot(b[0] - a[0], b[1] - a[1]);
+}
+
+/**
+ * Compute the coordinateTurn damping distance for interior waypoint `i`.
+ *
+ * Spec constraint: dampingDist[i] + dampingDist[i+1] < segmentLength(i, i+1).
+ * Clamping each side to MAX_DAMPING_FRAC × its shorter adjacent segment
+ * guarantees the sum is at most 2 × MAX_DAMPING_FRAC < 1 of that segment.
+ */
+function turnDamping(enuWps: readonly EnuPoint[], i: number): Meters {
+  const dPrev = enuSegLen(enuWps[i - 1]!, enuWps[i]!);
+  const dNext = enuSegLen(enuWps[i]!, enuWps[i + 1]!);
+  return meters(
+    Math.min(DESIRED_TURN_DAMPING_M, dPrev * MAX_DAMPING_FRAC, dNext * MAX_DAMPING_FRAC),
+  );
+}
+
+/** Nadir gimbal-down, hover, manual focus, infinite focus, hover — per reference WPML. */
+function buildStartActionGroup(pitchDeg: number): StartActionGroup {
+  return {
+    action: [
+      {
+        actionId: 0,
+        actionActuatorFunc: "gimbalRotate",
+        actionActuatorFuncParam: {
+          payloadPositionIndex: 0,
+          gimbalHeadingYawBase: "aircraft",
+          gimbalRotateMode: "absoluteAngle",
+          gimbalPitchRotateEnable: true,
+          gimbalPitchRotateAngle: degrees(pitchDeg),
+          gimbalRollRotateEnable: false,
+          gimbalRollRotateAngle: degrees(0),
+          gimbalYawRotateEnable: true,
+          gimbalYawRotateAngle: degrees(0),
+          gimbalRotateTimeEnable: false,
+          gimbalRotateTime: 10,
+        },
+      },
+      {
+        actionId: 1,
+        actionActuatorFunc: "hover",
+        actionActuatorFuncParam: { hoverTime: 0.5 },
+      },
+      {
+        actionId: 2,
+        actionActuatorFunc: "setFocusType",
+        actionActuatorFuncParam: { payloadPositionIndex: 0, cameraFocusType: "manual" },
+      },
+      {
+        actionId: 3,
+        actionActuatorFunc: "focus",
+        actionActuatorFuncParam: {
+          payloadPositionIndex: 0,
+          isPointFocus: false,
+          focusX: 0,
+          focusY: 0,
+          focusRegionWidth: 0,
+          focusRegionHeight: 0,
+          isInfiniteFocus: true,
+          isCalibrationFocus: false,
+        },
+      },
+      {
+        actionId: 4,
+        actionActuatorFunc: "hover",
+        actionActuatorFuncParam: { hoverTime: 1 },
+      },
+    ],
+  };
+}
+
+/** Build the three actions placed at the first waypoint of a shooting section. */
+function shootSectionStartActions(
+  pitchDeg: number,
+  shootInterval: number,
+  sectionStart: number,
+  sectionEnd: number,
+  groupIdStart: number,
+): { groups: import("../types/action.js").ActionGroup[]; nextGroupId: number } {
+  const betweenGroup: import("../types/action.js").ActionGroup = {
+    actionGroupId: groupIdStart,
+    actionGroupStartIndex: sectionStart,
+    actionGroupEndIndex: sectionEnd,
+    actionGroupMode: "sequence",
+    actionTrigger: { actionTriggerType: "betweenAdjacentPoints" },
+    action: [
+      {
+        actionId: 0,
+        actionActuatorFunc: "gimbalAngleLock",
+        actionActuatorFuncParam: { payloadPositionIndex: 0 },
+      },
+      {
+        actionId: 1,
+        actionActuatorFunc: "gimbalRotate",
+        actionActuatorFuncParam: {
+          payloadPositionIndex: 0,
+          gimbalHeadingYawBase: "aircraft",
+          gimbalRotateMode: "absoluteAngle",
+          gimbalPitchRotateEnable: true,
+          gimbalPitchRotateAngle: degrees(pitchDeg),
+          gimbalRollRotateEnable: false,
+          gimbalRollRotateAngle: degrees(0),
+          gimbalYawRotateEnable: false,
+          gimbalYawRotateAngle: degrees(0),
+          gimbalRotateTimeEnable: false,
+          gimbalRotateTime: 10,
+        },
+      },
+      {
+        actionId: 2,
+        actionActuatorFunc: "startTimeLapse",
+        actionActuatorFuncParam: {
+          payloadPositionIndex: 0,
+          useGlobalPayloadLensIndex: false,
+          payloadLensIndex: "visable",
+          minShootInterval: shootInterval,
+        },
+      },
+    ],
+  };
+
+  const timingGroup: import("../types/action.js").ActionGroup = {
+    actionGroupId: groupIdStart + 1,
+    actionGroupStartIndex: sectionStart,
+    actionGroupEndIndex: sectionEnd,
+    actionGroupMode: "sequence",
+    actionTrigger: { actionTriggerType: "multipleTiming", actionTriggerParam: shootInterval },
+    action: [
+      {
+        actionId: 0,
+        actionActuatorFunc: "gimbalRotate",
+        actionActuatorFuncParam: {
+          payloadPositionIndex: 0,
+          gimbalHeadingYawBase: "aircraft",
+          gimbalRotateMode: "absoluteAngle",
+          gimbalPitchRotateEnable: true,
+          gimbalPitchRotateAngle: degrees(pitchDeg),
+          gimbalRollRotateEnable: false,
+          gimbalRollRotateAngle: degrees(0),
+          gimbalYawRotateEnable: false,
+          gimbalYawRotateAngle: degrees(0),
+          gimbalRotateTimeEnable: false,
+          gimbalRotateTime: 10,
+        },
+      },
+    ],
+  };
+
+  return { groups: [betweenGroup, timingGroup], nextGroupId: groupIdStart + 2 };
+}
+
+/** Build the stop group placed at the last waypoint of a shooting section. */
+function shootSectionStopActions(
+  sectionEnd: number,
+  groupId: number,
+): import("../types/action.js").ActionGroup {
+  return {
+    actionGroupId: groupId,
+    actionGroupStartIndex: sectionEnd,
+    actionGroupEndIndex: sectionEnd,
+    actionGroupMode: "sequence",
+    actionTrigger: { actionTriggerType: "reachPoint" },
+    action: [
+      {
+        actionId: 0,
+        actionActuatorFunc: "stopTimeLapse",
+        actionActuatorFuncParam: { payloadPositionIndex: 0, payloadLensIndex: "visable" },
+      },
+      { actionId: 1, actionActuatorFunc: "gimbalAngleUnlock" } satisfies Action,
+    ],
+  };
+}
+
+/** Zero-dampingDist stop-turn (first/last waypoint of a section). */
+function stopTurn() {
+  return {
+    waypointTurnMode: "toPointAndStopWithDiscontinuityCurvature" as const,
+    waypointTurnDampingDist: meters(0),
+  };
+}
+
+/** Common heading param fields present on every mapping waypoint. */
+function mappingHeadingParam(headingAngle: number, angleEnable: boolean) {
+  return {
+    waypointHeadingMode: "followWayline" as const,
+    waypointHeadingAngle: degrees(headingAngle),
+    waypointPoiPoint: { lng: 0, lat: 0, height: meters(0) },
+    waypointHeadingAngleEnable: angleEnable,
+    waypointHeadingPathMode: "followBadArc" as const,
+    waypointHeadingPoiIndex: 0,
+  };
+}
+
+/** Common extra fields present on every mapping waypoint per reference WPML. */
+const COMMON_WP_EXTRAS = {
+  useStraightLine: true as const,
+  waypointGimbalHeadingParam: {
+    waypointGimbalPitchAngle: degrees(0),
+    waypointGimbalYawAngle: degrees(0),
+  },
+  isRisky: false as const,
+  waypointWorkType: 0,
+};
+
+/**
+ * 高程优化 (elevationOptimizeEnable) excursion — appended to the nadir grid:
+ * fly from the last nadir waypoint to the survey centroid and take an oblique shot
+ * there to enrich the DSM. WITHOUT this flag the route ends at the last grid
+ * waypoint — it does NOT detour to the centre (that detour is elevation optimization,
+ * not smart-swing). Mutates `placemarks` (appends two waypoints).
+ */
+function appendElevationExcursion(
+  placemarks: WaylinesPlacemark[],
+  folder: Mapping2dFolder,
+  origin: { lng: number; lat: number },
+  enuWps: readonly EnuPoint[],
+  shootInterval: number,
+  startGroupId: number,
+): void {
+  const lastNadirIdx = enuWps.length - 1;
+  const obliqueStartIdx = placemarks.length;
+  const obliqueEndIdx = obliqueStartIdx + 1;
+  const pitch = Number(folder.Placemark.quickOrthoMappingPitch ?? degrees(-45));
+  let nextGroupId = startGroupId;
+
+  // reachPoint — tilt gimbal to the oblique pitch then hover
+  const obliqueGimbalGroup: import("../types/action.js").ActionGroup = {
+    actionGroupId: nextGroupId++,
+    actionGroupStartIndex: obliqueStartIdx,
+    actionGroupEndIndex: obliqueStartIdx,
+    actionGroupMode: "sequence",
+    actionTrigger: { actionTriggerType: "reachPoint" },
+    action: [
+      {
+        actionId: 0,
+        actionActuatorFunc: "gimbalRotate",
+        actionActuatorFuncParam: {
+          payloadPositionIndex: 0,
+          gimbalHeadingYawBase: "aircraft",
+          gimbalRotateMode: "absoluteAngle",
+          gimbalPitchRotateEnable: true,
+          gimbalPitchRotateAngle: degrees(pitch),
+          gimbalRollRotateEnable: false,
+          gimbalRollRotateAngle: degrees(0),
+          gimbalYawRotateEnable: true,
+          gimbalYawRotateAngle: degrees(0),
+          gimbalRotateTimeEnable: false,
+          gimbalRotateTime: 10,
+        },
+      },
+      { actionId: 1, actionActuatorFunc: "hover", actionActuatorFuncParam: { hoverTime: 0.5 } },
+    ],
+  };
+
+  const obliqueStart = shootSectionStartActions(
+    pitch,
+    shootInterval,
+    obliqueStartIdx,
+    obliqueEndIdx,
+    nextGroupId,
+  );
+  nextGroupId = obliqueStart.nextGroupId;
+  const obliqueStop = shootSectionStopActions(obliqueEndIdx, nextGroupId);
+
+  const lastNadirCoord = enuToLngLat(enuWps[lastNadirIdx]!, origin);
+  const sumEnu = enuWps.reduce((acc, p) => [acc[0] + p[0], acc[1] + p[1]] as EnuPoint, [
+    0, 0,
+  ] as EnuPoint);
+  const centroidEnu: EnuPoint = [sumEnu[0] / enuWps.length, sumEnu[1] / enuWps.length];
+  const centroidCoord = enuToLngLat(centroidEnu, origin);
+  const obliqueHeading = bearingDeg(enuWps[lastNadirIdx]!, centroidEnu);
+
+  placemarks.push({
+    Point: { coordinates: lastNadirCoord }, // same position as last nadir
+    index: obliqueStartIdx,
+    executeHeight: folder.Placemark.height,
+    waypointSpeed: folder.autoFlightSpeed,
+    waypointHeadingParam: mappingHeadingParam(obliqueHeading, true),
+    waypointTurnParam: stopTurn(),
+    ...COMMON_WP_EXTRAS,
+    actionGroup: [obliqueGimbalGroup, ...obliqueStart.groups],
+  });
+
+  placemarks.push({
+    Point: { coordinates: centroidCoord },
+    index: obliqueEndIdx,
+    executeHeight: folder.Placemark.height,
+    waypointSpeed: folder.autoFlightSpeed,
+    waypointHeadingParam: mappingHeadingParam(0, false),
+    waypointTurnParam: stopTurn(),
+    ...COMMON_WP_EXTRAS,
+    actionGroup: [obliqueStop],
+  });
+}
+
+/**
+ * Ortho (nadir) wayline — covers 正射 and 正射+智能摆拍 (the swing is a folder-level
+ * quickOrthoMappingEnable flag over the same grid geometry, not extra waypoints).
+ *
+ * Action pattern (per reference WPML M4TD 正射采集):
+ *   - WP 0: two action groups (betweenAdjacentPoints startTimeLapse-init + multipleTiming gimbalCorrect)
+ *   - WP 1…N-2: no action groups
+ *   - WP N-1 (last): reachPoint stopTimeLapse group
+ *
+ * When `elevationOptimizeEnable` is set, a centroid excursion is appended (see
+ * `appendElevationExcursion`); otherwise the route ends at the last grid waypoint.
+ */
+function emitOrtho(
+  folder: Mapping2dFolder,
+  origin: { lng: number; lat: number },
+  enuWps: readonly EnuPoint[],
+  shootInterval: number,
+): WaylinesFolder {
+  const lastIndex = enuWps.length - 1;
+  const startActions = shootSectionStartActions(-90, shootInterval, 0, lastIndex, 0);
+  const stopGroup = shootSectionStopActions(lastIndex, startActions.nextGroupId);
+
+  const placemarks: WaylinesPlacemark[] = enuWps.map((enu, index) => {
+    const coord = enuToLngLat(enu, origin);
+    const isLast = index === lastIndex;
+    const headingAngle = isLast ? 0 : bearingDeg(enuWps[index]!, enuWps[index + 1]!);
+    const placemark: WaylinesPlacemark = {
       Point: { coordinates: coord },
       index,
-      executeHeight: folder.height,
+      executeHeight: folder.Placemark.height,
       waypointSpeed: folder.autoFlightSpeed,
-      waypointHeadingParam: {
-        waypointHeadingMode: "followWayline",
-        waypointHeadingAngle: degrees(headingAngle),
-        waypointHeadingPathMode: "followBadArc",
-      },
-      waypointTurnParam: { waypointTurnMode: "toPointAndPassWithContinuityCurvature" },
-      ...(actionGroup.length > 0 ? { actionGroup } : {}),
+      waypointHeadingParam: mappingHeadingParam(headingAngle, !isLast),
+      waypointTurnParam:
+        index === 0 || isLast
+          ? stopTurn()
+          : {
+              waypointTurnMode: "coordinateTurn",
+              waypointTurnDampingDist: turnDamping(enuWps, index),
+            },
+      ...COMMON_WP_EXTRAS,
     };
+    if (index === 0) {
+      placemark.actionGroup = startActions.groups;
+    } else if (isLast) {
+      placemark.actionGroup = [stopGroup];
+    }
+    return placemark;
   });
 
-  const waylineFolder: WaylinesFolder = {
+  if (folder.Placemark.elevationOptimizeEnable) {
+    appendElevationExcursion(
+      placemarks,
+      folder,
+      origin,
+      enuWps,
+      shootInterval,
+      startActions.nextGroupId + 1,
+    );
+  }
+
+  return {
     templateId: folder.templateId,
     waylineId: 0,
     executeHeightMode: heightModeToExecuteMode(folder),
     autoFlightSpeed: folder.autoFlightSpeed,
-    startActionGroup: {
-      actionGroupId: 65535,
-      actionGroupStartIndex: 0,
-      actionGroupEndIndex: 0,
-      actionGroupMode: "sequence",
-      actionTrigger: { actionTriggerType: "reachPoint" },
-      action: [
+    startActionGroup: buildStartActionGroup(-90),
+    Placemark: placemarks,
+  };
+}
+
+/**
+ * Single-pass smart-oblique / quick-ortho (smartObliqueEnable=true):
+ * The aircraft flies one grid while the gimbal swings (startSmartOblique/stopSmartOblique).
+ */
+function emitSmartOblique(
+  folder: Mapping2dFolder,
+  origin: { lng: number; lat: number },
+  enuWps: readonly EnuPoint[],
+): WaylinesFolder {
+  const lastIndex = enuWps.length - 1;
+  const pitch = folder.Placemark.smartObliqueGimbalPitch ?? degrees(-45);
+
+  const placemarks: WaylinesPlacemark[] = enuWps.map((enu, index) => {
+    const coord = enuToLngLat(enu, origin);
+    const isLast = index === lastIndex;
+    const headingAngle = isLast ? 0 : bearingDeg(enuWps[index]!, enuWps[index + 1]!);
+    const placemark: WaylinesPlacemark = {
+      Point: { coordinates: coord },
+      index,
+      executeHeight: folder.Placemark.height,
+      waypointSpeed: folder.autoFlightSpeed,
+      waypointHeadingParam: mappingHeadingParam(headingAngle, !isLast),
+      waypointTurnParam:
+        index === 0 || isLast
+          ? stopTurn()
+          : {
+              waypointTurnMode: "coordinateTurn",
+              waypointTurnDampingDist: turnDamping(enuWps, index),
+            },
+      ...COMMON_WP_EXTRAS,
+    };
+    if (index === 0) {
+      placemark.actionGroup = [
         {
-          actionId: 0,
-          actionActuatorFunc: "gimbalRotate",
-          actionActuatorFuncParam: {
-            payloadPositionIndex: 0,
-            gimbalHeadingYawBase: "north",
-            gimbalRotateMode: "absoluteAngle",
-            gimbalPitchRotateEnable: true,
-            gimbalPitchRotateAngle: degrees(-90),
-            gimbalRollRotateEnable: false,
-            gimbalRollRotateAngle: degrees(0),
-            gimbalYawRotateEnable: true,
-            gimbalYawRotateAngle: degrees(0),
-            gimbalRotateTimeEnable: false,
-            gimbalRotateTime: 10,
-          },
+          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 },
+            },
+          ],
+        },
+      ];
+    }
+    return placemark;
+  });
+
+  return {
+    templateId: folder.templateId,
+    waylineId: 0,
+    executeHeightMode: heightModeToExecuteMode(folder),
+    autoFlightSpeed: folder.autoFlightSpeed,
+    startActionGroup: buildStartActionGroup(Number(pitch)),
     Placemark: placemarks,
   };
-
-  return { missionConfig: template.missionConfig, Folder: [waylineFolder] };
 }
 
-function heightModeToExecuteMode(folder: Mapping2dFolder): ExecuteHeightMode {
-  switch (folder.waylineCoordinateSysParam.heightMode) {
-    case "EGM96":
-      return "WGS84";
-    case "relativeToStartPoint":
-      return "relativeToStartPoint";
-    case "aboveGroundLevel":
-    case "realTimeFollowSurface":
-      return "realTimeFollowSurface";
+export function planMapping2d(template: Mapping2dTemplate, options?: PlanOptions): Waylines {
+  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.",
+    );
   }
-}
+  // Smart-oblique flies a single omnidirectional swinging pass that must overfly the
+  // boundary on every side; ortho / quick-ortho stay tight to the area.
+  const standoff =
+    template.Folder.Placemark.smartObliqueEnable === true
+      ? smartObliqueStandoff(template.Folder)
+      : 0;
+  const { folder, origin, enuWps } = buildGrid(template, Number(options.lineSpacing), standoff);
+  const shootInterval = options.shootInterval ?? 2;
 
-// Suppress unused import warnings for re-exports
-void metersPerSecond;
+  if (folder.Placemark.smartObliqueEnable === true) {
+    return {
+      missionConfig: template.missionConfig,
+      Folder: [emitSmartOblique(folder, origin, enuWps)],
+    };
+  }
+  // 正射 and 正射+智能摆拍 share the nadir grid; the centroid detour is driven by
+  // elevationOptimizeEnable inside emitOrtho, not by quickOrthoMappingEnable.
+  return {
+    missionConfig: template.missionConfig,
+    Folder: [emitOrtho(folder, origin, enuWps, shootInterval)],
+  };
+}