@lumikmz/kmz 0.2.0 → 0.3.0

package/src/plan/plan-mapping3d.ts

@@ -1,90 +1,189 @@
 import { degrees } from "../types/branded.js";
-import type { Action, ActionGroup, GimbalRotateAction } from "../types/action.js";
-import type { ExecuteHeightMode } from "../types/enums.js";
+import type { Action, GimbalRotateAction } from "../types/action.js";
+import type { ExecuteHeightMode, WaypointHeadingMode } from "../types/enums.js";
 import type { Mapping3dFolder, Mapping3dTemplate } from "../types/template.js";
 import type { Waylines, WaylinesFolder } from "../types/waylines.js";
 import type { WaylinesPlacemark } from "../types/placemark.js";
+import { PlannerError } from "../types/errors.js";
 import {
   centroid,
   enuToLngLat,
   type EnuPoint,
   lngLatToEnu,
+  orientPathToHome,
   parseCoordinatesString,
-  scanWaypoints,
+  surveyGrid,
 } from "./geometry.js";
-
-const DEFAULT_HFOV_DEG = 84;
+import type { PlanOptions } from "./index.js";
 
 /**
- * Compile a `mapping3d` (oblique photography) template into 5 waylines:
- * one nadir (ortho) pass + four oblique passes (front/back/left/right).
+ * mapping3d expands to 5 wayline folders for a 5-direction oblique survey:
+ * one nadir pass plus four 45°-oblique passes looking forward / right / back / left.
+ *
+ * Each pass is its own boustrophedon grid:
+ *   - nadir + forward + backward fly the **main axis** (θ = folder.Placemark.direction);
+ *   - right + left fly the **perpendicular axis** (θ ± 90°) so the aircraft flies
+ *     nose-forward while the gimbal looks sideways.
+ * The two passes sharing an axis are interleaved by half a line spacing so they
+ * don't overlap and together give denser coverage.
+ *
+ * The look direction is the aircraft heading: each oblique pass fixes its heading
+ * to its look azimuth and the gimbal is pitched down relative to the **aircraft**
+ * (gimbalHeadingYawBase: "aircraft", yaw 0) — NOT relative to north.
  */
-export function planMapping3d(template: Mapping3dTemplate): Waylines {
+
+type PassPitch = "nadir" | "inclined";
+
+interface PassSpec {
+  /** Grid flight-line axis, relative to folder.Placemark.direction (°). */
+  axisOffsetDeg: number;
+  /** Fixed heading / look azimuth, relative to folder.Placemark.direction (°). */
+  headingOffsetDeg: number;
+  /** nadir → −90° gimbal, inclined → folder.Placemark.inclinedGimbalPitch. */
+  pitch: PassPitch;
+  /** followWayline for nadir, fixed for obliques. */
+  headingMode: WaypointHeadingMode;
+  /** Shift the grid by half a line spacing to interleave with its axis-mate. */
+  halfPhase: boolean;
+  /**
+   * Look direction along the flight axis: +1 = looks toward +axis, −1 = toward
+   * −axis, 0 = nadir. The grid is shifted by −lookSign·standoff so it overhangs
+   * the boundary only on the side opposite the look (the camera images ahead).
+   */
+  lookSign: -1 | 0 | 1;
+  /** Timed-shot interval (s). */
+  interval: number;
+}
+
+const PASSES: readonly PassSpec[] = [
+  // 0 — nadir (ortho)
+  { axisOffsetDeg: 0, headingOffsetDeg: 0, pitch: "nadir", headingMode: "followWayline", halfPhase: false, lookSign: 0, interval: 2.0 }, // prettier-ignore
+  // 1 — forward oblique (look +θ)
+  { axisOffsetDeg: 0, headingOffsetDeg: 0, pitch: "inclined", headingMode: "fixed", halfPhase: false, lookSign: 1, interval: 2.5 }, // prettier-ignore
+  // 2 — right oblique (look θ+90), perpendicular grid
+  { axisOffsetDeg: 90, headingOffsetDeg: 90, pitch: "inclined", headingMode: "fixed", halfPhase: false, lookSign: 1, interval: 2.5 }, // prettier-ignore
+  // 3 — backward oblique (look θ+180), main axis, interleaved with forward
+  { axisOffsetDeg: 0, headingOffsetDeg: 180, pitch: "inclined", headingMode: "fixed", halfPhase: true, lookSign: -1, interval: 2.5 }, // prettier-ignore
+  // 4 — left oblique (look θ−90), perpendicular grid, interleaved with right
+  { axisOffsetDeg: 90, headingOffsetDeg: -90, pitch: "inclined", headingMode: "fixed", halfPhase: true, lookSign: -1, interval: 2.5 }, // prettier-ignore
+];
+
+/** Normalize an angle to (−180, 180]. */
+function wrap180(deg: number): number {
+  return ((((deg + 180) % 360) + 360) % 360) - 180;
+}
+
+export function planMapping3d(template: Mapping3dTemplate, options?: PlanOptions): Waylines {
+  if (options?.lineSpacing == null) {
+    throw new PlannerError(
+      "mapping3d requires options.lineSpacing — calculate 2·h·tan(HFOV/2)·(1−sideOverlap) in the demo and pass it in.",
+    );
+  }
   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 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);
-
-  const enuWps = scanWaypoints(enuPolygon, lineSpacing);
-
-  const passes = [
-    { headingAngle: 0, gimbalPitch: -90, minShootInterval: 2.0 },
-    { headingAngle: 0, gimbalPitch: folder.inclinedGimbalPitch, minShootInterval: 2.5 },
-    { headingAngle: 180, gimbalPitch: folder.inclinedGimbalPitch, minShootInterval: 2.5 },
-    { headingAngle: 90, gimbalPitch: folder.inclinedGimbalPitch, minShootInterval: 2.5 },
-    { headingAngle: -90, gimbalPitch: folder.inclinedGimbalPitch, minShootInterval: 2.5 },
-  ];
-
-  const Folder: WaylinesFolder[] = passes.map((pass, i) =>
-    buildObliquePass(
-      folder,
-      i,
-      origin,
-      enuWps,
-      pass.headingAngle,
-      pass.gimbalPitch,
-      pass.minShootInterval,
-    ),
+  const ringEnu = ring.map((p) => lngLatToEnu(p, origin));
+  const baseDirection = Number(folder.Placemark.direction);
+  const lineSpacing = Number(options.lineSpacing);
+  const inclined = folder.Placemark.inclinedGimbalPitch;
+
+  const pitchAbs = Math.abs(Number(inclined));
+  const sinP = pitchAbs > 0 && pitchAbs < 90 ? Math.sin((pitchAbs * Math.PI) / 180) : 1;
+  const tanP = pitchAbs > 0 && pitchAbs < 90 ? Math.tan((pitchAbs * Math.PI) / 180) : Infinity;
+
+  // Oblique stand-off: a camera pitched |p|° below horizontal at height h images a
+  // ground point h/tan(|p|) ahead of the aircraft along its look (= flight) axis. The
+  // oblique grid is therefore shifted opposite the look by this distance, so it
+  // overhangs the boundary only on the back side (and pulls in on the look side) —
+  // matching how the camera actually covers the area. Clamp to 3·h so a near-
+  // horizontal pitch can't produce a runaway grid.
+  const standoff = Math.min(
+    Number(folder.Placemark.height) / tanP,
+    Number(folder.Placemark.height) * 3,
   );
 
-  return { missionConfig: template.missionConfig, Folder };
+  // Oblique line spacing is wider than nadir: a tilted camera images from a longer
+  // slant range (h/sin|p|), so its cross-track footprint is 1/sin|p| larger and the
+  // same overlap is reached with fewer lines. The four oblique directions together
+  // supply the multi-angle coverage, so each pass is intentionally sparse.
+  const obliqueSpacing = lineSpacing / sinP;
+
+  return {
+    missionConfig: template.missionConfig,
+    Folder: PASSES.map((pass, i) => {
+      const isOblique = pass.pitch === "inclined";
+      const passSpacing = isOblique ? obliqueSpacing : lineSpacing;
+      const enuWps = orientPathToHome(
+        surveyGrid(ringEnu, {
+          directionDeg: baseDirection + pass.axisOffsetDeg,
+          marginM: folder.Placemark.margin,
+          lineSpacing: passSpacing,
+          phaseOffsetM: pass.halfPhase ? passSpacing / 2 : 0,
+          lengthwiseShiftM: -pass.lookSign * standoff,
+        }),
+        origin,
+        template.missionConfig.takeOffRefPoint,
+      );
+      return buildPass(folder, i, origin, enuWps, {
+        headingMode: pass.headingMode,
+        headingAngle: degrees(wrap180(baseDirection + pass.headingOffsetDeg)),
+        gimbalPitch: pass.pitch === "nadir" ? degrees(-90) : inclined,
+        interval: pass.interval,
+      });
+    }),
+  };
 }
 
-function buildObliquePass(
+interface PassConfig {
+  headingMode: WaypointHeadingMode;
+  headingAngle: ReturnType<typeof degrees>;
+  gimbalPitch: ReturnType<typeof degrees>;
+  interval: number;
+}
+
+function buildPass(
   folder: Mapping3dFolder,
   waylineId: number,
   origin: { lng: number; lat: number },
   enuWps: readonly EnuPoint[],
-  headingAngle: number,
-  gimbalPitch: number,
-  minShootInterval: number,
+  cfg: PassConfig,
 ): WaylinesFolder {
   const lastIndex = enuWps.length - 1;
-
   const placemarks: WaylinesPlacemark[] = enuWps.map((enu, index) => {
-    const coord = enuToLngLat(enu, origin);
     const placemark: WaylinesPlacemark = {
-      Point: { coordinates: coord },
+      Point: { coordinates: enuToLngLat(enu, origin) },
       index,
-      executeHeight: folder.height,
-      waypointSpeed: folder.autoFlightSpeed,
+      executeHeight: folder.Placemark.height,
+      waypointSpeed: folder.Placemark.inclinedFlightSpeed,
       waypointHeadingParam: {
-        waypointHeadingMode: "fixed",
-        waypointHeadingAngle: degrees(headingAngle),
+        waypointHeadingMode: cfg.headingMode,
+        waypointHeadingAngle: cfg.headingAngle,
         waypointHeadingPathMode: "followBadArc",
       },
       waypointTurnParam: { waypointTurnMode: "toPointAndPassWithContinuityCurvature" },
     };
-
-    const groups = waypointActionGroups(index, lastIndex, gimbalPitch, minShootInterval);
-    if (groups.length > 0) placemark.actionGroup = groups;
+    if (index === 0) {
+      placemark.actionGroup = [
+        {
+          actionGroupId: 0,
+          actionGroupStartIndex: 0,
+          actionGroupEndIndex: lastIndex,
+          actionGroupMode: "sequence",
+          actionTrigger: { actionTriggerType: "reachPoint" },
+          action: [gimbalRotate(0, cfg.gimbalPitch)],
+        },
+        {
+          actionGroupId: 1,
+          actionGroupStartIndex: 0,
+          actionGroupEndIndex: lastIndex,
+          actionGroupMode: "sequence",
+          actionTrigger: { actionTriggerType: "multipleTiming", actionTriggerParam: cfg.interval },
+          action: [takePhoto(0)],
+        },
+      ];
+    }
     return placemark;
   });
 
@@ -92,65 +191,25 @@ function buildObliquePass(
     templateId: folder.templateId,
     waylineId,
     executeHeightMode: heightModeToExecuteMode(folder.waylineCoordinateSysParam.heightMode),
-    autoFlightSpeed: folder.autoFlightSpeed,
-    startActionGroup: startGimbalRotateGroup(gimbalPitch),
+    autoFlightSpeed: folder.Placemark.inclinedFlightSpeed,
+    startActionGroup: {
+      action: [gimbalRotate(0, cfg.gimbalPitch)],
+    },
     Placemark: placemarks,
   };
 }
 
-function waypointActionGroups(
-  index: number,
-  lastIndex: number,
-  gimbalPitch: number,
-  minShootInterval: number,
-): ActionGroup[] {
-  if (index === 0) {
-    return [
-      {
-        actionGroupId: 0,
-        actionGroupStartIndex: 0,
-        actionGroupEndIndex: lastIndex,
-        actionGroupMode: "sequence",
-        actionTrigger: { actionTriggerType: "reachPoint" },
-        action: [gimbalRotate(0, gimbalPitch)],
-      },
-      {
-        actionGroupId: 1,
-        actionGroupStartIndex: 0,
-        actionGroupEndIndex: lastIndex,
-        actionGroupMode: "sequence",
-        actionTrigger: {
-          actionTriggerType: "multipleTiming",
-          actionTriggerParam: minShootInterval,
-        },
-        action: [takePhoto(0)],
-      },
-    ];
-  }
-  return [];
-}
-
-function startGimbalRotateGroup(gimbalPitch: number): ActionGroup {
-  return {
-    actionGroupId: 65535,
-    actionGroupStartIndex: 0,
-    actionGroupEndIndex: 0,
-    actionGroupMode: "sequence",
-    actionTrigger: { actionTriggerType: "reachPoint" },
-    action: [gimbalRotate(0, gimbalPitch)],
-  };
-}
-
-function gimbalRotate(actionId: number, pitch: number): GimbalRotateAction {
+/** Oblique gimbal: pitched down relative to the aircraft nose (yaw base = aircraft). */
+function gimbalRotate(actionId: number, pitch: ReturnType<typeof degrees>): GimbalRotateAction {
   return {
     actionId,
     actionActuatorFunc: "gimbalRotate",
     actionActuatorFuncParam: {
       payloadPositionIndex: 0,
-      gimbalHeadingYawBase: "north",
+      gimbalHeadingYawBase: "aircraft",
       gimbalRotateMode: "absoluteAngle",
       gimbalPitchRotateEnable: true,
-      gimbalPitchRotateAngle: degrees(pitch),
+      gimbalPitchRotateAngle: pitch,
       gimbalRollRotateEnable: false,
       gimbalRollRotateAngle: degrees(0),
       gimbalYawRotateEnable: false,

package/src/plan/plan.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { degrees, meters, metersPerSecond } from "../types/branded.js";
 import { DroneEnum, PayloadEnum } from "../types/drone-payload.js";
-import type { Mapping2dTemplate, WaypointTemplate } from "../types/template.js";
+import type { Mapping2dTemplate, Mapping3dTemplate, WaypointTemplate } from "../types/template.js";
 import { plan } from "./index.js";
 
 const missionConfig = {
@@ -69,14 +69,14 @@ describe("plan", () => {
         templateId: 1,
         waylineCoordinateSysParam: { coordinateMode: "WGS84", heightMode: "relativeToStartPoint" },
         autoFlightSpeed: metersPerSecond(10),
-        elevationOptimizeEnable: false,
-        shootType: "distance",
-        direction: degrees(0),
-        margin: 0,
-        overlap: { orthoCameraOverlapH: 80, orthoCameraOverlapW: 70 },
-        ellipsoidHeight: meters(150),
-        height: meters(100),
         Placemark: {
+          elevationOptimizeEnable: false,
+          shootType: "distance",
+          direction: degrees(0),
+          margin: 0,
+          overlap: { orthoCameraOverlapH: 80, orthoCameraOverlapW: 70 },
+          ellipsoidHeight: meters(150),
+          height: meters(100),
           Polygon: {
             outerBoundaryIs: {
               LinearRing: {
@@ -89,8 +89,262 @@ describe("plan", () => {
       },
     };
 
-    const waylines = plan(template);
+    const waylines = plan(template, { lineSpacing: meters(45) });
     expect(waylines.Folder).toHaveLength(1);
     expect(waylines.Folder[0]!.Placemark.length).toBeGreaterThan(0);
   });
+
+  it("accepts surface-follow + dsmFile on a mapping2d waylineCoordinateSysParam", () => {
+    const template: Mapping2dTemplate = {
+      missionConfig,
+      Folder: {
+        templateType: "mapping2d",
+        templateId: 2,
+        waylineCoordinateSysParam: {
+          coordinateMode: "WGS84",
+          heightMode: "aboveGroundLevel",
+          surfaceFollowModeEnable: true,
+          isRealtimeSurfaceFollow: false,
+          dsmFile: "wpmz/res/dsm/test.tif",
+        },
+        autoFlightSpeed: metersPerSecond(10),
+        Placemark: {
+          elevationOptimizeEnable: false,
+          shootType: "distance",
+          direction: degrees(0),
+          margin: 0,
+          overlap: { orthoCameraOverlapH: 80, orthoCameraOverlapW: 70 },
+          ellipsoidHeight: meters(150),
+          height: meters(100),
+          Polygon: {
+            outerBoundaryIs: {
+              LinearRing: {
+                coordinates:
+                  "113.938,22.5397,0 113.940,22.5397,0 113.940,22.5407,0 113.938,22.5407,0 113.938,22.5397,0",
+              },
+            },
+          },
+        },
+      },
+    };
+    expect(plan(template, { lineSpacing: meters(30) }).Folder).toHaveLength(1);
+  });
+
+  it("mapping2d ortho: grid density follows provided lineSpacing", () => {
+    const template: Mapping2dTemplate = {
+      missionConfig,
+      Folder: {
+        templateType: "mapping2d",
+        templateId: 1,
+        waylineCoordinateSysParam: { coordinateMode: "WGS84", heightMode: "relativeToStartPoint" },
+        autoFlightSpeed: metersPerSecond(10),
+        Placemark: {
+          elevationOptimizeEnable: false,
+          shootType: "distance",
+          direction: degrees(0),
+          margin: 0,
+          overlap: { orthoCameraOverlapH: 80, orthoCameraOverlapW: 70 },
+          ellipsoidHeight: meters(150),
+          height: meters(100),
+          Polygon: {
+            outerBoundaryIs: {
+              LinearRing: {
+                // ~400m × ~400m square
+                coordinates:
+                  "113.9380,22.5397,0 113.9419,22.5397,0 113.9419,22.5433,0 113.9380,22.5433,0 113.9380,22.5397,0",
+              },
+            },
+          },
+        },
+      },
+    };
+    // lineSpacing=45m → ~9 lines across 400m → ~18 placemarks
+    const wl = plan(template, { lineSpacing: meters(45) });
+    expect(wl.Folder).toHaveLength(1);
+    const n = wl.Folder[0]!.Placemark.length;
+    expect(n).toBeGreaterThanOrEqual(12);
+    expect(n).toBeLessThanOrEqual(28);
+  });
+
+  it("elevationOptimizeEnable appends a centroid excursion; off adds nothing", () => {
+    const ortho = (elevationOptimizeEnable: boolean): Mapping2dTemplate => ({
+      missionConfig,
+      Folder: {
+        templateType: "mapping2d",
+        templateId: 1,
+        waylineCoordinateSysParam: { coordinateMode: "WGS84", heightMode: "relativeToStartPoint" },
+        autoFlightSpeed: metersPerSecond(10),
+        Placemark: {
+          elevationOptimizeEnable,
+          shootType: "distance",
+          direction: degrees(0),
+          margin: 0,
+          overlap: { orthoCameraOverlapH: 80, orthoCameraOverlapW: 70 },
+          ellipsoidHeight: meters(150),
+          height: meters(100),
+          Polygon: {
+            outerBoundaryIs: {
+              LinearRing: {
+                coordinates:
+                  "113.9380,22.5397,0 113.9419,22.5397,0 113.9419,22.5433,0 113.9380,22.5433,0 113.9380,22.5397,0",
+              },
+            },
+          },
+        },
+      },
+    });
+    const off = plan(ortho(false), { lineSpacing: meters(45) }).Folder[0]!;
+    const on = plan(ortho(true), { lineSpacing: meters(45) }).Folder[0]!;
+    // The excursion is exactly two extra waypoints ending at the survey centroid.
+    expect(on.Placemark.length).toBe(off.Placemark.length + 2);
+    const last = on.Placemark[on.Placemark.length - 1]!.Point.coordinates;
+    expect(last.lng).toBeCloseTo(113.93995, 3); // centroid lng
+    expect(last.lat).toBeCloseTo(22.5415, 3); // centroid lat
+    // Without elevation optimization the route must NOT detour to the centroid.
+    const offLast = off.Placemark[off.Placemark.length - 1]!.Point.coordinates;
+    expect(
+      Math.abs(offLast.lng - 113.93995) > 0.0005 || Math.abs(offLast.lat - 22.5415) > 0.0005,
+    ).toBe(true);
+  });
+
+  it("mapping2d + smartObliqueEnable emits one folder with smart-oblique actions", () => {
+    const template: Mapping2dTemplate = {
+      missionConfig,
+      Folder: {
+        templateType: "mapping2d",
+        templateId: 1,
+        waylineCoordinateSysParam: { coordinateMode: "WGS84", heightMode: "relativeToStartPoint" },
+        autoFlightSpeed: metersPerSecond(10),
+        Placemark: {
+          elevationOptimizeEnable: false,
+          smartObliqueEnable: true,
+          smartObliqueGimbalPitch: degrees(-45),
+          shootType: "time",
+          direction: degrees(0),
+          margin: 0,
+          overlap: { orthoCameraOverlapH: 80, orthoCameraOverlapW: 70 },
+          ellipsoidHeight: meters(150),
+          height: meters(100),
+          Polygon: {
+            outerBoundaryIs: {
+              LinearRing: {
+                coordinates:
+                  "113.9380,22.5397,0 113.9419,22.5397,0 113.9419,22.5433,0 113.9380,22.5433,0 113.9380,22.5397,0",
+              },
+            },
+          },
+        },
+      },
+    };
+    const wl = plan(template, { lineSpacing: meters(45) });
+    expect(wl.Folder).toHaveLength(1);
+    const funcs = wl.Folder[0]!.Placemark.flatMap((p) =>
+      (p.actionGroup ?? []).flatMap((g) => g.action.map((a) => a.actionActuatorFunc)),
+    );
+    expect(funcs).toContain("startSmartOblique");
+    expect(funcs).toContain("stopSmartOblique");
+
+    // The camera swings omnidirectionally, so the polygon is dilated by the
+    // stand-off and the grid overflies the boundary on EVERY side. Polygon spans
+    // lat 22.5397–22.5433, lng 113.9380–113.9419; at h=100, swing 45° the stand-off
+    // ≈ 100 m ≈ 0.0009°, so waypoints extend past all four edges.
+    const pts = wl.Folder[0]!.Placemark.map((p) => p.Point.coordinates);
+    const lats = pts.map((p) => p.lat);
+    const lngs = pts.map((p) => p.lng);
+    expect(Math.max(...lats)).toBeGreaterThan(22.5436); // past north edge
+    expect(Math.min(...lats)).toBeLessThan(22.5394); // past south edge
+    expect(Math.max(...lngs)).toBeGreaterThan(113.942); // past east edge
+    expect(Math.min(...lngs)).toBeLessThan(113.9377); // past west edge
+  });
+
+  it("mapping3d expands to 5 distinct passes: nadir + forward/right/back/left oblique", () => {
+    const template: Mapping3dTemplate = {
+      missionConfig,
+      Folder: {
+        templateType: "mapping3d",
+        templateId: 0,
+        waylineCoordinateSysParam: { coordinateMode: "WGS84", heightMode: "relativeToStartPoint" },
+        autoFlightSpeed: metersPerSecond(10),
+        Placemark: {
+          inclinedGimbalPitch: degrees(-45),
+          inclinedFlightSpeed: metersPerSecond(10),
+          shootType: "time",
+          direction: degrees(0),
+          margin: 0,
+          overlap: { orthoCameraOverlapH: 80, orthoCameraOverlapW: 70 },
+          ellipsoidHeight: meters(150),
+          height: meters(100),
+          Polygon: {
+            outerBoundaryIs: {
+              LinearRing: {
+                // ~800 m (E-W) × ~220 m (N-S) rectangle — non-square so the
+                // main-axis and perpendicular-axis grids differ in line count.
+                coordinates:
+                  "113.9380,22.5397,0 113.9460,22.5397,0 113.9460,22.5417,0 113.9380,22.5417,0 113.9380,22.5397,0",
+              },
+            },
+          },
+        },
+      },
+    };
+    const wl = plan(template, { lineSpacing: meters(45) });
+    expect(wl.Folder).toHaveLength(5);
+    expect(wl.Folder.map((f) => f.waylineId)).toEqual([0, 1, 2, 3, 4]);
+
+    const gimbalParam = (i: number) => {
+      const action = wl.Folder[i]!.startActionGroup!.action[0]!;
+      if (action.actionActuatorFunc !== "gimbalRotate") throw new Error("expected gimbalRotate");
+      return action.actionActuatorFuncParam;
+    };
+    const startPitch = (i: number) => Number(gimbalParam(i).gimbalPitchRotateAngle);
+    const yawBase = (i: number) => gimbalParam(i).gimbalHeadingYawBase;
+    const heading = (i: number) => wl.Folder[i]!.Placemark[0]!.waypointHeadingParam!;
+
+    // Nadir looks straight down; the four obliques are pitched to the inclined angle.
+    expect(startPitch(0)).toBe(-90);
+    expect([startPitch(1), startPitch(2), startPitch(3), startPitch(4)]).toEqual([
+      -45, -45, -45, -45,
+    ]);
+
+    // Gimbal pitch is relative to the aircraft nose (not north) for every pass.
+    expect([0, 1, 2, 3, 4].every((i) => yawBase(i) === "aircraft")).toBe(true);
+
+    // Nadir follows the path; obliques fix heading to their look azimuth.
+    expect(heading(0).waypointHeadingMode).toBe("followWayline");
+    expect([1, 2, 3, 4].every((i) => heading(i).waypointHeadingMode === "fixed")).toBe(true);
+    // direction=0 → forward 0°, right +90°, back ±180°, left −90°.
+    expect(Number(heading(1).waypointHeadingAngle)).toBe(0);
+    expect(Number(heading(2).waypointHeadingAngle)).toBe(90);
+    expect(Math.abs(Number(heading(3).waypointHeadingAngle))).toBe(180);
+    expect(Number(heading(4).waypointHeadingAngle)).toBe(-90);
+
+    // Perpendicular passes (2,4) run a different axis → different line count
+    // than the main-axis passes (0,1,3) on this non-square polygon.
+    expect(wl.Folder[2]!.Placemark.length).not.toBe(wl.Folder[0]!.Placemark.length);
+
+    // Forward (1) and backward (3) share the main axis but are interleaved by
+    // half a line spacing → their first waypoints differ.
+    expect(wl.Folder[1]!.Placemark[0]!.Point.coordinates).not.toEqual(
+      wl.Folder[3]!.Placemark[0]!.Point.coordinates,
+    );
+
+    // direction=0 → main-axis lines run N-S; the stand-off shifts each oblique grid
+    // along that axis, opposite its look, so it overhangs the boundary on ONE side.
+    const latRange = (i: number) => {
+      const lats = wl.Folder[i]!.Placemark.map((p) => p.Point.coordinates.lat);
+      return { min: Math.min(...lats), max: Math.max(...lats) };
+    };
+    const nadir = latRange(0);
+    const fwd = latRange(1); // looks +θ (north) → shifted south
+    const back = latRange(3); // looks −θ (south) → shifted north
+    // Forward overhangs the south edge but pulls in from the north (look) side.
+    expect(fwd.min).toBeLessThan(nadir.min);
+    expect(fwd.max).toBeLessThan(nadir.max);
+    // Backward overhangs the opposite (north) edge.
+    expect(back.max).toBeGreaterThan(nadir.max);
+
+    // Oblique passes use wider line spacing (slant-range factor) → fewer flight
+    // lines than the same-axis nadir pass, despite covering the same width.
+    expect(wl.Folder[1]!.Placemark.length).toBeLessThan(wl.Folder[0]!.Placemark.length);
+  });
 });