@lumikmz/kmz 0.7.0 → 0.8.0

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

@@ -0,0 +1,540 @@
+import { describe, expect, it } from "vitest";
+import { degrees, meters, metersPerSecond } from "../types/branded.js";
+import type { MappingStripTemplate } from "../types/template.js";
+import { deriveMappingStrip } from "./plan-mapping-strip.js";
+import { plan } from "./index.js";
+import { haversineMeters } from "./geometry.js";
+import { validate } from "../validate/index.js";
+
+const missionConfig = {
+  flyToWaylineMode: "safely" as const,
+  finishAction: "goHome" as const,
+  exitOnRCLost: "goContinue" as const,
+  executeRCLostAction: "goBack" as const,
+  takeOffSecurityHeight: meters(20),
+  globalTransitionalSpeed: metersPerSecond(10),
+  globalRTHHeight: meters(100),
+  droneInfo: { droneEnumValue: 100, droneSubEnumValue: 1 },
+  payloadInfo: [{ payloadEnumValue: 99, payloadSubEnumValue: 2, payloadPositionIndex: 0 }],
+};
+
+function stripTemplate(
+  patch: Partial<MappingStripTemplate["Folder"]["Placemark"]> = {},
+): MappingStripTemplate {
+  return {
+    missionConfig,
+    Folder: {
+      templateType: "mappingStrip",
+      templateId: 0,
+      waylineCoordinateSysParam: {
+        coordinateMode: "WGS84",
+        heightMode: "relativeToStartPoint",
+        globalShootHeight: meters(100),
+      },
+      autoFlightSpeed: metersPerSecond(10),
+      payloadParam: { payloadPositionIndex: 0, imageFormat: ["visable"] },
+      Placemark: {
+        caliFlightEnable: false,
+        shootType: "time",
+        direction: degrees(0),
+        margin: 0,
+        singleLineEnable: false,
+        cuttingDistance: 100,
+        boundaryOptimEnable: false,
+        leftExtend: 10,
+        rightExtend: 20,
+        includeCenterEnable: false,
+        overlap: { orthoCameraOverlapH: 80, orthoCameraOverlapW: 70 },
+        LineString: { coordinates: "0,0,0 0.0025,0,0" },
+        ellipsoidHeight: meters(100),
+        height: meters(100),
+        stripUseTemplateAltitude: false,
+        ...patch,
+      },
+    },
+  };
+}
+
+const options = {
+  crossTrackFootprint: meters(20),
+  lineSpacing: meters(20),
+  photoSpacing: meters(10),
+  shootInterval: 1,
+};
+
+function officialPerpendicularTemplate(): MappingStripTemplate {
+  const template = stripTemplate({
+    direction: degrees(90),
+    cuttingDistance: 500,
+    leftExtend: 20,
+    rightExtend: 20,
+    LineString: {
+      coordinates:
+        "113.93997035048,22.5865507192322,0 " +
+        "113.940518577471,22.5865663826002,0 " +
+        "113.941066804979,22.5865820441085,0 " +
+        "113.942725461619,22.5866167444266,0 " +
+        "113.942561470892,22.5850786058152,0 " +
+        "113.941014448042,22.5844259068028,0",
+    },
+  });
+  template.missionConfig.takeOffRefPoint = {
+    lng: 113.937913,
+    lat: 22.586278,
+    height: meters(52.064712),
+  };
+  template.Folder.autoFlightSpeed = metersPerSecond(11);
+  template.Folder.payloadParam!.imageFormat = ["visable", "ir"];
+  return template;
+}
+
+const officialPerpendicularOptions = {
+  crossTrackFootprint: meters(58.0385533694263),
+  lineSpacing: meters(17.41156601082789),
+  photoSpacing: meters(9.286168539108209),
+  shootInterval: 9.286168539108209 / 11,
+  stripDirection: "perpendicular" as const,
+};
+
+function officialParallelTemplate(): MappingStripTemplate {
+  const template = stripTemplate({
+    direction: degrees(0),
+    cuttingDistance: 500,
+    leftExtend: 10,
+    rightExtend: 10,
+    stripMergedRegions: [[1, 3]],
+    LineString: {
+      coordinates:
+        "113.941248708397,22.5864247808395,0 " +
+        "113.941253956609,22.587043600882,0 " +
+        "113.943240592044,22.5870606460195,0 " +
+        "113.943272505926,22.5835995315534,0 " +
+        "113.939088405347,22.5834895035782,0 " +
+        "113.939067471512,22.5855352765462,0 " +
+        "113.941243230473,22.5855676449574,0",
+    },
+  });
+  template.Folder.payloadParam!.imageFormat = ["visable", "ir"];
+  return template;
+}
+
+const officialParallelOptions = {
+  crossTrackFootprint: meters(89.995),
+  lineSpacing: meters(26.9985),
+  photoSpacing: meters(14),
+  shootInterval: 1.4,
+  stripDirection: "parallel" as const,
+};
+
+describe("deriveMappingStrip", () => {
+  it("validates distinct center points and positive geometry parameters", () => {
+    const template = stripTemplate({
+      LineString: { coordinates: "0,0,0 0,0,0" },
+      leftExtend: -1,
+      cuttingDistance: 0,
+      stripMergedRegions: [[2, 1]],
+    });
+    const issues = validate(template);
+
+    expect(issues.map(({ path }) => path)).toEqual(
+      expect.arrayContaining([
+        "Folder.Placemark.LineString",
+        "Folder.Placemark.leftExtend",
+        "Folder.Placemark.cuttingDistance",
+        "Folder.Placemark.stripMergedRegions",
+      ]),
+    );
+  });
+
+  it("cuts the center line at exact accumulated distances", () => {
+    const derived = deriveMappingStrip(stripTemplate(), options);
+
+    expect(derived.regions).toHaveLength(3);
+    expect(derived.regions.map((region) => Number(region.startDistance))).toEqual([0, 100, 200]);
+    expect(Number(derived.regions[0]!.endDistance)).toBeCloseTo(100, 6);
+    expect(Number(derived.regions[1]!.endDistance)).toBeCloseTo(200, 6);
+    expect(Number(derived.regions[2]!.endDistance)).toBeCloseTo(277.99, 0);
+  });
+
+  it("applies FlightHub one-based inclusive merged-region ranges", () => {
+    const template = stripTemplate({
+      cuttingDistance: 500,
+      stripMergedRegions: [[1, 3]],
+      LineString: { coordinates: "0,0,0 0.016,0,0" },
+    });
+    const merged = deriveMappingStrip(template, options);
+    const split = deriveMappingStrip(
+      stripTemplate({
+        cuttingDistance: 500,
+        LineString: { coordinates: "0,0,0 0.016,0,0" },
+      }),
+      options,
+    );
+
+    expect(split.regions).toHaveLength(4);
+    expect(merged.regions).toHaveLength(2);
+    expect(merged.regions[0]!.sourceRegionIndexes).toEqual([0, 1, 2]);
+    expect(Number(merged.regions[0]!.endDistance)).toBeCloseTo(1_500, 5);
+    expect(plan(template, options).Folder).toHaveLength(2);
+  });
+
+  it("builds an asymmetric flat-capped corridor", () => {
+    const derived = deriveMappingStrip(
+      stripTemplate({ cuttingDistance: 1_000, singleLineEnable: true }),
+      options,
+    );
+    const polygon = derived.regions[0]!.polygon;
+    const north = Math.max(...polygon.map((point) => point.lat));
+    const south = Math.min(...polygon.map((point) => point.lat));
+
+    expect(north).toBeCloseTo(10 / 111_195, 6);
+    expect(south).toBeCloseTo(-20 / 111_195, 6);
+    expect(polygon[0]!.lng).toBeCloseTo(0, 8);
+    expect(polygon.at(-1)!.lng).toBeCloseTo(0, 8);
+  });
+
+  it("chamfers the outside of every bend in one strip region", () => {
+    const derived = deriveMappingStrip(
+      stripTemplate({
+        cuttingDistance: 10_000,
+        leftExtend: 20,
+        rightExtend: 20,
+        LineString: {
+          coordinates: "0,0,0 0.001,0,0 0.001,0.001,0 0.002,0.001,0",
+        },
+      }),
+      options,
+    );
+
+    expect(derived.regions).toHaveLength(1);
+    expect(derived.regions[0]!.polygon).toHaveLength(10);
+  });
+
+  it("uses neighboring center-line directions when a region ends at a bend", () => {
+    const derived = deriveMappingStrip(
+      stripTemplate({
+        cuttingDistance: 100,
+        leftExtend: 20,
+        rightExtend: 20,
+        LineString: { coordinates: "0,0,0 0.0007,0,0 0.0007,0.0007,0" },
+      }),
+      options,
+    );
+
+    expect(derived.regions).toHaveLength(2);
+    expect(derived.regions.map((region) => region.polygon.length)).toEqual([5, 5]);
+  });
+
+  it("forces the center line into a symmetric multi-line route", () => {
+    const derived = deriveMappingStrip(
+      stripTemplate({
+        cuttingDistance: 1_000,
+        leftExtend: 50,
+        rightExtend: 50,
+        includeCenterEnable: true,
+      }),
+      options,
+    );
+
+    expect(derived.flightRoutes[0]!.routeOffsets.map(Number)).toEqual([-40, -20, 0, 20, 40]);
+    expect(derived.flightRoutes[0]!.routeLines).toHaveLength(5);
+    expect(derived.flightRoutes[0]!.executablePath).toHaveLength(10);
+  });
+
+  it("keeps one route when the camera footprint is wider than the corridor", () => {
+    const derived = deriveMappingStrip(stripTemplate({ cuttingDistance: 1_000 }), {
+      ...options,
+      crossTrackFootprint: meters(100),
+      lineSpacing: meters(30),
+    });
+
+    expect(derived.flightRoutes[0]!.routeOffsets).toHaveLength(1);
+    expect(Number(derived.flightRoutes[0]!.routeOffsets[0])).toBe(0);
+  });
+
+  it("lays out infrared routes by overlap spacing without shrinking by half-footprint", () => {
+    const infraredTemplate = stripTemplate({
+      cuttingDistance: 1_000,
+      leftExtend: 20,
+      rightExtend: 20,
+    });
+    infraredTemplate.Folder.payloadParam!.imageFormat = ["ir"];
+    const infrared = deriveMappingStrip(infraredTemplate, {
+      ...options,
+      crossTrackFootprint: meters(90),
+      lineSpacing: meters(27),
+    });
+    const visible = deriveMappingStrip(
+      stripTemplate({ cuttingDistance: 1_000, leftExtend: 20, rightExtend: 20 }),
+      {
+        ...options,
+        crossTrackFootprint: meters(200),
+        lineSpacing: meters(60.5),
+      },
+    );
+
+    expect(infrared.flightRoutes[0]!.routeOffsets.map(Number)).toEqual([-13.5, 13.5]);
+    expect(visible.flightRoutes[0]!.routeOffsets.map(Number)).toEqual([0]);
+    expect(infrared.flightRoutes[0]!.segments.map(({ kind }) => kind)).toEqual([
+      "work",
+      "turn",
+      "work",
+    ]);
+    expect(infrared.flightRoutes[0]!.segments[1]!.photoEnabled).toBe(false);
+  });
+
+  it("adds the center line without removing infrared side routes", () => {
+    const template = stripTemplate({
+      cuttingDistance: 1_000,
+      leftExtend: 20,
+      rightExtend: 20,
+      includeCenterEnable: true,
+    });
+    template.Folder.payloadParam!.imageFormat = ["ir"];
+    const derived = deriveMappingStrip(template, {
+      ...options,
+      crossTrackFootprint: meters(90),
+      lineSpacing: meters(27),
+    });
+
+    expect(derived.flightRoutes[0]!.routeOffsets.map(Number)).toEqual([-13.5, 0, 13.5]);
+  });
+
+  it("uses an even off-center layout unless includeCenterEnable is enabled", () => {
+    const withoutCenterTemplate = stripTemplate({
+      cuttingDistance: 1_000,
+      leftExtend: 40,
+      rightExtend: 40,
+      includeCenterEnable: false,
+    });
+    withoutCenterTemplate.Folder.payloadParam!.imageFormat = ["visable", "ir"];
+    const withCenterTemplate = stripTemplate({
+      cuttingDistance: 1_000,
+      leftExtend: 40,
+      rightExtend: 40,
+      includeCenterEnable: true,
+    });
+    withCenterTemplate.Folder.payloadParam!.imageFormat = ["visable", "ir"];
+    const withoutCenter = deriveMappingStrip(withoutCenterTemplate, {
+      ...options,
+      crossTrackFootprint: meters(90),
+      lineSpacing: meters(27),
+    });
+    const withCenter = deriveMappingStrip(withCenterTemplate, {
+      ...options,
+      crossTrackFootprint: meters(90),
+      lineSpacing: meters(27),
+    });
+
+    expect(withoutCenter.flightRoutes[0]!.routeOffsets.map(Number)).toEqual([-13.5, 13.5]);
+    expect(withCenter.flightRoutes[0]!.routeOffsets.map(Number)).toEqual([-27, 0, 27]);
+  });
+
+  it("adds a separate oblique center-line segment only for elevation optimization", () => {
+    const off = deriveMappingStrip(
+      stripTemplate({ cuttingDistance: 1_000, elevationOptimizeEnable: false }),
+      options,
+    );
+    const on = deriveMappingStrip(
+      stripTemplate({ cuttingDistance: 1_000, elevationOptimizeEnable: true }),
+      options,
+    );
+
+    expect(off.flightRoutes[0]!.segments.some(({ kind }) => kind === "elevationOptimize")).toBe(
+      false,
+    );
+    expect(on.flightRoutes[0]!.segments.at(-1)).toMatchObject({
+      kind: "elevationOptimize",
+      photoEnabled: true,
+    });
+    expect(Number(on.flightRoutes[0]!.length)).toBeGreaterThan(Number(off.flightRoutes[0]!.length));
+  });
+
+  it("generates perpendicular work lines through each strip region", () => {
+    const derived = deriveMappingStrip(stripTemplate({ cuttingDistance: 1_000 }), {
+      ...options,
+      stripDirection: "perpendicular",
+    });
+    const firstLine = derived.flightRoutes[0]!.routeLines[0]!;
+
+    expect(firstLine).toHaveLength(2);
+    expect(Math.abs(firstLine[0]!.lng - firstLine[1]!.lng)).toBeLessThan(
+      Math.abs(firstLine[0]!.lat - firstLine[1]!.lat),
+    );
+  });
+
+  it("matches FlightHub perpendicular segmentation and local scan-line counts", () => {
+    const derived = deriveMappingStrip(
+      officialPerpendicularTemplate(),
+      officialPerpendicularOptions,
+    );
+
+    expect(derived.regions.map((region) => Number(region.endDistance))).toEqual([
+      expect.closeTo(454.815, 2),
+      expect.closeTo(629.44, 2),
+    ]);
+    expect(derived.flightRoutes.map((route) => route.routeLines.length)).toEqual([31, 11]);
+  });
+
+  it("connects adjacent perpendicular scan lines at their nearest ends", () => {
+    const derived = deriveMappingStrip(
+      officialPerpendicularTemplate(),
+      officialPerpendicularOptions,
+    );
+    const lines = derived.flightRoutes[0]!.routeLines.slice(0, 8);
+
+    for (let index = 1; index < lines.length; index++) {
+      const previousEnd = lines[index - 1]!.at(-1)!;
+      const next = lines[index]!;
+      expect(haversineMeters(previousEnd, next[0]!)).toBeLessThan(
+        haversineMeters(previousEnd, next.at(-1)!),
+      );
+    }
+  });
+
+  it("matches FlightHub parallel region and route-line counts", () => {
+    const derived = deriveMappingStrip(officialParallelTemplate(), officialParallelOptions);
+
+    expect(derived.regions).toHaveLength(2);
+    expect(derived.flightRoutes.map((route) => route.routeLines.length)).toEqual([1, 1]);
+    expect(derived.flightRoutes.map((route) => route.executablePath.length)).toEqual([5, 3]);
+  });
+
+  it("reverses only the region execution order", () => {
+    const normal = deriveMappingStrip(stripTemplate(), options);
+    const reversed = deriveMappingStrip(stripTemplate(), {
+      ...options,
+      regionOrderReversed: true,
+    });
+
+    expect(reversed.flightRoutes.map(({ regionId }) => regionId)).toEqual(
+      normal.flightRoutes.map(({ regionId }) => regionId).reverse(),
+    );
+    expect(reversed.regions.map(({ id }) => id)).toEqual(normal.regions.map(({ id }) => id));
+  });
+
+  it("orients the first region toward the reference takeoff point", () => {
+    const template = stripTemplate({ cuttingDistance: 1_000, singleLineEnable: true });
+    template.missionConfig.takeOffRefPoint = { lng: 0.0026, lat: 0, height: meters(0) };
+    const derived = deriveMappingStrip(template, options);
+
+    expect(derived.flightRoutes[0]!.executablePath[0]!.lng).toBeGreaterThan(0.002);
+  });
+
+  it("keeps map transit segments separate from each region executable path", () => {
+    const derived = deriveMappingStrip(stripTemplate(), options);
+
+    for (let index = 1; index < derived.flightRoutes.length; index++) {
+      const previous = derived.flightRoutes[index - 1]!;
+      const current = derived.flightRoutes[index]!;
+      expect(current.segments[0]).toMatchObject({ kind: "transit", photoEnabled: false });
+      expect(current.segments[0]!.points[0]).toEqual(previous.executablePath.at(-1));
+      expect(current.segments[0]!.points[1]).toEqual(current.executablePath[0]);
+    }
+  });
+
+  it("chooses the shortest transition from all serpentine route orientations", () => {
+    const template = stripTemplate({
+      cuttingDistance: 100,
+      leftExtend: 50,
+      rightExtend: 50,
+      includeCenterEnable: true,
+    });
+    template.missionConfig.takeOffRefPoint = {
+      lng: 0,
+      lat: -40 / 111_195,
+      height: meters(0),
+    };
+    const derived = deriveMappingStrip(template, options);
+
+    const transitionLengths = derived.flightRoutes.slice(1).map((route) => {
+      const transition = route.segments[0]!;
+      expect(transition).toMatchObject({ kind: "transit", photoEnabled: false });
+      return haversineMeters(transition.points[0]!, transition.points[1]!);
+    });
+
+    expect(transitionLengths).toHaveLength(2);
+    expect(transitionLengths.every((length) => length < 1)).toBe(true);
+  });
+});
+
+describe("plan(mappingStrip)", () => {
+  it("matches FlightHub perpendicular waypoint and continuous-capture group counts", () => {
+    const waylines = plan(officialPerpendicularTemplate(), officialPerpendicularOptions);
+
+    expect(waylines.Folder.map((folder) => folder.Placemark.length)).toEqual([62, 22]);
+    expect(
+      waylines.Folder.map(
+        (folder) => folder.Placemark.flatMap((point) => point.actionGroup ?? []).length,
+      ),
+    ).toEqual([3, 3]);
+  });
+
+  it("emits one wayline folder per distance-cut region with damped turns", () => {
+    const waylines = plan(stripTemplate(), options);
+
+    expect(waylines.Folder).toHaveLength(3);
+    expect(waylines.Folder.map((folder) => folder.waylineId)).toEqual([0, 1, 2]);
+    expect(waylines.Folder[0]!.Placemark[1]!.waypointTurnParam.waypointTurnMode).toBe(
+      "coordinateTurn",
+    );
+    expect(
+      Number(waylines.Folder[0]!.Placemark[1]!.waypointTurnParam.waypointTurnDampingDist),
+    ).toBeLessThanOrEqual(10);
+  });
+
+  it("uses the selected payload lenses in shooting actions", () => {
+    const template = stripTemplate({ cuttingDistance: 1_000 });
+    template.Folder.payloadParam!.imageFormat = ["visable", "ir"];
+    const waylines = plan(template, options);
+    const actions = waylines.Folder[0]!.Placemark.flatMap((point) =>
+      (point.actionGroup ?? []).flatMap((group) => group.action),
+    );
+    const start = actions.find((action) => action.actionActuatorFunc === "startTimeLapse");
+
+    expect(start?.actionActuatorFuncParam.payloadLensIndex).toEqual(["visable", "ir"]);
+  });
+
+  it("uses one continuous time-lapse run across all work lines", () => {
+    const template = stripTemplate({ cuttingDistance: 1_000, leftExtend: 20, rightExtend: 20 });
+    template.Folder.payloadParam!.imageFormat = ["ir"];
+    const waylines = plan(template, {
+      ...options,
+      crossTrackFootprint: meters(90),
+      lineSpacing: meters(27),
+    });
+    const groups = waylines.Folder[0]!.Placemark.flatMap((point) => point.actionGroup ?? []);
+    const starts = groups.filter((group) =>
+      group.action.some((action) => action.actionActuatorFunc === "startTimeLapse"),
+    );
+
+    expect(groups).toHaveLength(3);
+    expect(starts).toHaveLength(1);
+    expect(starts[0]!.actionGroupStartIndex).toBe(0);
+    expect(starts[0]!.actionGroupEndIndex).toBe(waylines.Folder[0]!.Placemark.length - 1);
+  });
+
+  it("exports each region executable path without its map-only transit segment", () => {
+    const template = stripTemplate();
+    const derived = deriveMappingStrip(template, options);
+    const waylines = plan(template, options);
+
+    waylines.Folder.forEach((folder, index) => {
+      expect(folder.Placemark.map(({ Point }) => Point.coordinates)).toEqual(
+        derived.flightRoutes[index]!.executablePath,
+      );
+    });
+  });
+
+  it("uses a -45 degree gimbal pitch only for elevation optimization", () => {
+    const pitches = (enabled: boolean) =>
+      plan(stripTemplate({ cuttingDistance: 1_000, elevationOptimizeEnable: enabled }), options)
+        .Folder[0]!.Placemark.flatMap((point) => point.actionGroup ?? [])
+        .flatMap((group) => group.action)
+        .filter((action) => action.actionActuatorFunc === "gimbalRotate")
+        .map((action) => Number(action.actionActuatorFuncParam.gimbalPitchRotateAngle));
+
+    expect(pitches(false)).not.toContain(-45);
+    expect(pitches(true)).toContain(-45);
+  });
+});