@lumikmz/kmz 0.11.0 → 0.11.1

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

@@ -0,0 +1,349 @@
+import { describe, expect, it } from "vite-plus/test";
+import { degrees, meters, metersPerSecond, type LngLat } from "../types/branded.js";
+import type { MappingStripTemplate } from "../types/template.js";
+import { PlannerError } from "../types/errors.js";
+import { deriveMappingStrip, planMappingStrip } from "./plan-mapping-strip.js";
+import { enuToLngLat, haversineMeters, lngLatToEnu, type EnuPoint } from "./geometry.js";
+
+const ORIGIN: LngLat = { lng: 118.35, lat: 35.05 };
+const OPTIONS = {
+  crossTrackFootprint: meters(90),
+  lineSpacing: meters(27),
+  photoSpacing: meters(10),
+  shootInterval: 1,
+};
+
+function template(
+  points: readonly LngLat[],
+  patch: Partial<MappingStripTemplate["Folder"]["Placemark"]> = {},
+): MappingStripTemplate {
+  return {
+    missionConfig: {
+      flyToWaylineMode: "safely",
+      finishAction: "goHome",
+      exitOnRCLost: "goContinue",
+      executeRCLostAction: "goBack",
+      takeOffSecurityHeight: meters(20),
+      globalTransitionalSpeed: metersPerSecond(10),
+      globalRTHHeight: meters(100),
+      droneInfo: { droneEnumValue: 100, droneSubEnumValue: 1 },
+      payloadInfo: [{ payloadEnumValue: 99, payloadPositionIndex: 0 }],
+    },
+    Folder: {
+      templateType: "mappingStrip",
+      templateId: 0,
+      waylineCoordinateSysParam: { coordinateMode: "WGS84", heightMode: "EGM96" },
+      autoFlightSpeed: metersPerSecond(10),
+      payloadParam: { payloadPositionIndex: 0, imageFormat: ["visable", "ir"] },
+      Placemark: {
+        caliFlightEnable: false,
+        shootType: "time",
+        direction: degrees(0),
+        margin: 0,
+        singleLineEnable: false,
+        cuttingDistance: 350,
+        boundaryOptimEnable: false,
+        leftExtend: 20,
+        rightExtend: 20,
+        includeCenterEnable: false,
+        overlap: { orthoCameraOverlapH: 80, orthoCameraOverlapW: 70 },
+        LineString: { coordinates: points.map((p) => `${p.lng},${p.lat},0`).join(" ") },
+        ellipsoidHeight: meters(100),
+        height: meters(100),
+        stripUseTemplateAltitude: false,
+        ...patch,
+      },
+    },
+  };
+}
+
+function fromMeters(points: readonly EnuPoint[], patch = {}) {
+  return template(
+    points.map((point) => enuToLngLat(point, ORIGIN)),
+    patch,
+  );
+}
+
+function hasCrossing(ring: readonly LngLat[]): boolean {
+  const points = ring.map((point) => lngLatToEnu(point, ring[0]!));
+  const side = (a: EnuPoint, b: EnuPoint, c: EnuPoint) =>
+    (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+  for (let i = 0; i < points.length; i++) {
+    for (let j = i + 2; j < points.length; j++) {
+      if (i === 0 && j === points.length - 1) continue;
+      const a = points[i]!;
+      const b = points[(i + 1) % points.length]!;
+      const c = points[j]!;
+      const d = points[(j + 1) % points.length]!;
+      if (side(a, b, c) * side(a, b, d) < -1e-6 && side(c, d, a) * side(c, d, b) < -1e-6)
+        return true;
+    }
+  }
+  return false;
+}
+
+function covers(ring: readonly LngLat[], point: LngLat): boolean {
+  const vertices = ring.map((p) => lngLatToEnu(p, point));
+  let inside = false;
+  for (let i = 0, j = vertices.length - 1; i < vertices.length; j = i++) {
+    const a = vertices[i]!;
+    const b = vertices[j]!;
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    const t = Math.max(0, Math.min(1, -(a[0] * dx + a[1] * dy) / (dx * dx + dy * dy)));
+    if (Math.hypot(a[0] + t * dx, a[1] + t * dy) < 0.05) return true;
+    if (a[1] > 0 !== b[1] > 0 && ((b[0] - a[0]) * -a[1]) / (b[1] - a[1]) + a[0] > 0)
+      inside = !inside;
+  }
+  return inside;
+}
+
+describe("mapping strip corner geometry", () => {
+  it("reports the complete horizontal mission with the configured transit speed and finish action", () => {
+    const mission = fromMeters(
+      [
+        [0, 0],
+        [300, 0],
+      ],
+      { singleLineEnable: true, cuttingDistance: 1_000 },
+    );
+    mission.missionConfig.takeOffRefPoint = {
+      ...enuToLngLat([-100, 0], ORIGIN),
+      height: meters(0),
+    };
+    mission.missionConfig.globalTransitionalSpeed = metersPerSecond(20);
+    const returning = deriveMappingStrip(mission, OPTIONS);
+    expect(returning.estimatedDuration).toBeCloseTo(55, 2);
+    expect(Number(returning.totalFlightLength)).toBeCloseTo(800, 2);
+    mission.missionConfig.finishAction = "noAction";
+    const staying = deriveMappingStrip(mission, OPTIONS);
+    expect(staying.estimatedDuration).toBeCloseTo(35, 2);
+    expect(Number(staying.totalFlightLength)).toBeCloseTo(400, 2);
+  });
+  for (const angle of [15, 30, 45, 60, 90]) {
+    for (const sign of [-1, 1]) {
+      it(`keeps ${angle} degree ${sign < 0 ? "right" : "left"} corners simple when split or merged`, () => {
+        const rad = (angle * Math.PI) / 180;
+        const points: EnuPoint[] = [
+          [300, 0],
+          [0, 0],
+          [300 * Math.cos(rad), sign * 300 * Math.sin(rad)],
+        ];
+        for (const cuttingDistance of [350, 1_000]) {
+          for (const [leftExtend, rightExtend] of [
+            [20, 20],
+            [10, 35],
+          ]) {
+            const derived = deriveMappingStrip(
+              fromMeters(points, { cuttingDistance, leftExtend, rightExtend }),
+              OPTIONS,
+            );
+            expect(hasCrossing(derived.surveyArea)).toBe(false);
+            for (const region of derived.regions) expect(hasCrossing(region.polygon)).toBe(false);
+          }
+        }
+      });
+    }
+  }
+
+  it("shares the offset seam endpoints between adjacent parallel flight routes", () => {
+    const derived = deriveMappingStrip(
+      fromMeters([
+        [300, 0],
+        [0, 0],
+        [260, 150],
+      ]),
+      OPTIONS,
+    );
+    expect(derived.flightRoutes).toHaveLength(2);
+    const endpoints = derived.flightRoutes.map((route) =>
+      route.routeLines
+        .flatMap((line) => [line[0]!, line.at(-1)!])
+        .filter((p) => haversineMeters(p, ORIGIN) < 100),
+    );
+    expect(endpoints[0]).toHaveLength(2);
+    expect(endpoints[1]).toHaveLength(2);
+    for (const endpoint of endpoints[0]!) {
+      expect(
+        Math.min(...endpoints[1]!.map((other) => haversineMeters(endpoint, other))),
+      ).toBeLessThan(0.05);
+    }
+  });
+
+  it("keeps acute perpendicular work lines inside their square-joined region", () => {
+    for (const cuttingDistance of [350, 1_000]) {
+      const derived = deriveMappingStrip(
+        fromMeters(
+          [
+            [300, 0],
+            [0, 0],
+            [260, 150],
+          ],
+          { cuttingDistance },
+        ),
+        { ...OPTIONS, stripDirection: "perpendicular" },
+      );
+      for (const route of derived.flightRoutes) {
+        const region = derived.regions.find((r) => r.id === route.regionId)!;
+        for (const point of route.routeLines.flat())
+          expect(covers(region.polygon, point)).toBe(true);
+      }
+    }
+  });
+
+  it("bounds perpendicular line counts by the square corridor for a narrow one-sided bend", () => {
+    const angle = Math.PI / 180;
+    const derived = deriveMappingStrip(
+      fromMeters(
+        [
+          [100, 0],
+          [0, 0],
+          [100 * Math.cos(angle), -100 * Math.sin(angle)],
+        ],
+        {
+          cuttingDistance: 1_000,
+          leftExtend: 0,
+          rightExtend: 20,
+        },
+      ),
+      { ...OPTIONS, stripDirection: "perpendicular" },
+    );
+    expect(derived.flightRoutes[0]!.routeLines.length).toBeLessThanOrEqual(12);
+  });
+
+  it("rejects excessive perpendicular line counts before generating the grid", () => {
+    expect(() =>
+      deriveMappingStrip(
+        fromMeters([
+          [0, 0],
+          [300, 0],
+        ]),
+        {
+          ...OPTIONS,
+          stripDirection: "perpendicular",
+          lineSpacing: meters(0.1),
+        },
+      ),
+    ).toThrow(PlannerError);
+  });
+
+  it("clips parallel work lines when distance cuts fall inside an acute join", () => {
+    const derived = deriveMappingStrip(
+      fromMeters(
+        [
+          [300, 0],
+          [0, 0],
+          [260, 150],
+        ],
+        { cuttingDistance: 50 },
+      ),
+      { ...OPTIONS, crossTrackFootprint: meters(10), lineSpacing: meters(10) },
+    );
+    for (const route of derived.flightRoutes) {
+      const region = derived.regions.find((r) => r.id === route.regionId)!;
+      expect(route.routeOffsets).toHaveLength(route.routeLines.length);
+      for (const line of route.routeLines) {
+        for (const point of line) expect(covers(region.polygon, point)).toBe(true);
+      }
+    }
+  });
+
+  it("accepts an acute bend with a redundant collinear control point", () => {
+    const derived = deriveMappingStrip(
+      fromMeters(
+        [
+          [300, 0],
+          [5, 0],
+          [0, 0],
+          [260, 150],
+        ],
+        { cuttingDistance: 1_000 },
+      ),
+      OPTIONS,
+    );
+    expect(hasCrossing(derived.surveyArea)).toBe(false);
+    for (const route of derived.flightRoutes) {
+      const region = derived.regions.find((r) => r.id === route.regionId)!;
+      for (const point of route.routeLines.flat()) expect(covers(region.polygon, point)).toBe(true);
+    }
+  });
+
+  it("matches the outer square join and inner intersection in the supplied FlightHub export", () => {
+    // Geometry-only excerpts from docs/wpmz/template.kml and waylines.wpml.
+    // Allow 0.3 m for local ENU versus FlightHub's geodesic projection.
+    const source = [
+      { lng: 113.928721193053, lat: 22.5853407272811 },
+      { lng: 113.94147792621, lat: 22.5841462210489 },
+      { lng: 113.939227972615, lat: 22.5786467306102 },
+      { lng: 113.931390810642, lat: 22.5791428669172 },
+      { lng: 113.935648166968, lat: 22.5807314873742 },
+    ];
+    const derived = deriveMappingStrip(
+      template(source, {
+        cuttingDistance: 1_000,
+        leftExtend: 40,
+        rightExtend: 40,
+        stripMergedRegions: [[2, 3]],
+      }),
+      OPTIONS,
+    );
+    const expected = [
+      { lng: 113.931277468103, lat: 22.5790284117379 },
+      { lng: 113.931261027934, lat: 22.5791237956315 },
+      { lng: 113.931244587743, lat: 22.5792191795235 },
+      { lng: 113.931969360415, lat: 22.5792278822111 },
+    ];
+    const actual = derived.flightRoutes.flatMap((route) => route.executablePath);
+    for (const point of expected) {
+      expect(Math.min(...actual.map((other) => haversineMeters(point, other)))).toBeLessThan(0.3);
+    }
+    expect(hasCrossing(derived.surveyArea)).toBe(false);
+  });
+
+  it("limits turn damping to one third of the shorter adjacent leg as in FlightHub", () => {
+    const waylines = planMappingStrip(
+      fromMeters(
+        [
+          [0, 0],
+          [300, 0],
+        ],
+        { cuttingDistance: 1_000 },
+      ),
+      OPTIONS,
+    );
+    const points = waylines.Folder[0]!.Placemark;
+    expect(Number(points[1]!.waypointTurnParam.waypointTurnDampingDist)).toBeCloseTo(9, 2);
+    expect(points[0]!.waypointTurnParam.waypointTurnMode).toBe(
+      "toPointAndStopWithDiscontinuityCurvature",
+    );
+    expect(points.at(-1)!.waypointTurnParam.waypointTurnMode).toBe(
+      "toPointAndStopWithDiscontinuityCurvature",
+    );
+  });
+
+  it("rejects a complete reversal instead of emitting a crossed corridor", () => {
+    expect(() =>
+      deriveMappingStrip(
+        fromMeters([
+          [0, 0],
+          [300, 0],
+          [0, 0],
+        ]),
+        OPTIONS,
+      ),
+    ).toThrow(PlannerError);
+  });
+
+  it("rejects an inner join that runs past the available short legs", () => {
+    expect(() =>
+      deriveMappingStrip(
+        fromMeters([
+          [10, 0],
+          [0, 0],
+          [10, 2],
+        ]),
+        OPTIONS,
+      ),
+    ).toThrow(PlannerError);
+  });
+});

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

@@ -1,9 +1,9 @@
-import { describe, expect, it } from "vitest";
-import { degrees, meters, metersPerSecond } from "../types/branded.js";
+import { describe, expect, it } from "vite-plus/test";
+import { degrees, meters, metersPerSecond, type LngLat } 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 { centroid, enuToLngLat, haversineMeters, lngLatToEnu, type EnuPoint } from "./geometry.js";
 import { validate } from "../validate/index.js";
 
 const missionConfig = {
@@ -538,3 +538,134 @@ describe("plan(mappingStrip)", () => {
     expect(pitches(true)).toContain(-45);
   });
 });
+
+const ORIGIN: LngLat = { lng: 118.35, lat: 35.05 };
+
+function templateFromMeters(
+  points: readonly EnuPoint[],
+  cuttingDistance: number,
+  leftExtend = 20,
+  rightExtend = 20,
+): MappingStripTemplate {
+  return stripTemplate({
+    cuttingDistance,
+    leftExtend,
+    rightExtend,
+    LineString: {
+      coordinates: points
+        .map((point) => {
+          const { lng, lat } = enuToLngLat(point, ORIGIN);
+          return `${lng},${lat},0`;
+        })
+        .join(" "),
+    },
+  });
+}
+
+function ringArea(ring: readonly EnuPoint[]): number {
+  let doubleArea = 0;
+  for (let index = 0; index < ring.length; index++) {
+    const a = ring[index]!;
+    const b = ring[(index + 1) % ring.length]!;
+    doubleArea += a[0] * b[1] - b[0] * a[1];
+  }
+  return Math.abs(doubleArea) / 2;
+}
+
+function ringContains(ring: readonly EnuPoint[], [x, y]: EnuPoint): boolean {
+  let inside = false;
+  for (let index = 0, previous = ring.length - 1; index < ring.length; previous = index++) {
+    const a = ring[index]!;
+    const b = ring[previous]!;
+    if (a[1] > y !== b[1] > y && x < ((b[0] - a[0]) * (y - a[1])) / (b[1] - a[1]) + a[0])
+      inside = !inside;
+  }
+  return inside;
+}
+
+function analyzeStrip(
+  points: readonly EnuPoint[],
+  cuttingDistance: number,
+  leftExtend = 20,
+  rightExtend = 20,
+) {
+  const template = templateFromMeters(points, cuttingDistance, leftExtend, rightExtend);
+  const derived = deriveMappingStrip(template, options);
+  const tuples = template.Folder.Placemark.LineString.coordinates.split(/\s+/).map((tuple) => {
+    const [lng, lat] = tuple.split(",").map(Number) as [number, number];
+    return { lng, lat } as LngLat;
+  });
+  const origin = centroid(tuples);
+  return {
+    derived,
+    rings: derived.regions.map((region) =>
+      region.polygon.map((point) => lngLatToEnu(point, origin)),
+    ),
+    corridor: derived.surveyArea.map((point) => lngLatToEnu(point, origin)),
+    centerLine: tuples.map((point) => lngLatToEnu(point, origin)),
+  };
+}
+
+function midpointProbes(centerLine: readonly EnuPoint[]): EnuPoint[] {
+  return centerLine.slice(1).flatMap((point, index) => {
+    const start = centerLine[index]!;
+    return [0.25, 0.5, 0.75].map(
+      (t) =>
+        [start[0] + (point[0] - start[0]) * t, start[1] + (point[1] - start[1]) * t] as EnuPoint,
+    );
+  });
+}
+
+describe("mapping strip region tiling", () => {
+  it("cuts adjacent regions along the shared bisector seam", () => {
+    const { derived, rings, corridor, centerLine } = analyzeStrip(
+      [
+        [0, 0],
+        [300, 0],
+        [300, 300],
+        [600, 300],
+      ],
+      350,
+    );
+
+    expect(rings).toHaveLength(3);
+    const sum = rings.reduce((total, ring) => total + ringArea(ring), 0);
+    expect(sum).toBeCloseTo(ringArea(corridor), 6);
+    expect(derived.surveyAreaSize).toBeCloseTo(sum, 4);
+    for (const probe of midpointProbes(centerLine)) {
+      expect(rings.filter((ring) => ringContains(ring, probe))).toHaveLength(1);
+    }
+  });
+
+  it("splits a fold-back corner into exactly one region per point", () => {
+    const { rings, centerLine } = analyzeStrip(
+      [
+        [0, 0],
+        [300, 0],
+        [300, 300],
+        [0, 300],
+        [220, 180],
+      ],
+      350,
+    );
+
+    expect(rings).toHaveLength(4);
+    for (const probe of midpointProbes(centerLine)) {
+      expect(rings.filter((ring) => ringContains(ring, probe))).toHaveLength(1);
+    }
+  });
+
+  it("keeps collinear synthetic cuts exact", () => {
+    const { rings, corridor } = analyzeStrip(
+      [
+        [0, 0],
+        [800, 0],
+      ],
+      200,
+    );
+
+    expect(rings).toHaveLength(4);
+    const sum = rings.reduce((total, ring) => total + ringArea(ring), 0);
+    expect(sum).toBeCloseTo(ringArea(corridor), 6);
+  });
+});