@lumikmz/kmz 0.11.0 → 0.11.1

package/src/plan/plan-target-detection.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "vite-plus/test";
 import { degrees, meters, metersPerSecond } from "../types/branded.js";
 import type { TargetDetectionTemplate } from "../types/template.js";
 import { plan } from "./index.js";

package/src/plan/plan.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "vite-plus/test";
 import { degrees, meters, metersPerSecond } from "../types/branded.js";
 import { DroneEnum, PayloadEnum } from "../types/drone-payload.js";
 import type { Mapping2dTemplate, Mapping3dTemplate, WaypointTemplate } from "../types/template.js";

package/src/plan/strip-route-order.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, it } from "vite-plus/test";
+import { selectStripRouteCandidates, type StripRouteCandidate } from "./strip-route-order.js";
+import * as stripOrder from "./strip-route-order.js";
+
+function route(patch: Partial<StripRouteCandidate> = {}): StripRouteCandidate {
+  return {
+    start: [0, 0],
+    end: [10, 0],
+    entryDirection: [1, 0],
+    exitDirection: [1, 0],
+    length: 10,
+    ...patch,
+  };
+}
+
+describe("strip region transition ordering", () => {
+  it("chooses a slightly longer transfer when it avoids reversing the entry heading", () => {
+    const previous = route({ end: [0, 0] });
+    const reverse = route({ start: [10, 0], entryDirection: [-1, 0] });
+    const aligned = route({ start: [12, 0] });
+    expect(selectStripRouteCandidates([[previous], [reverse, aligned]])).toEqual([0, 1]);
+  });
+
+  it("prefers approaching the shared junction over cutting across a bent strip", () => {
+    const diagonal = Math.SQRT1_2;
+    const previous = route({ end: [0, 0], exitDirection: [diagonal, diagonal] });
+    const across = route({ start: [10, 0], entryDirection: [1, 0] });
+    const along = route({ start: [0, 12], entryDirection: [0, 1] });
+    expect(selectStripRouteCandidates([[previous], [across, along]], undefined, [[0, 10]])).toEqual(
+      [0, 1],
+    );
+  });
+
+  it("includes the candidate's internal flight length", () => {
+    expect(selectStripRouteCandidates([[route({ length: 100 }), route({ length: 10 })]])).toEqual([
+      1,
+    ]);
+  });
+
+  it("keeps heading preferences soft when the aligned transfer would be much longer", () => {
+    const previous = route({ end: [0, 0] });
+    expect(
+      selectStripRouteCandidates([
+        [previous],
+        [route({ start: [10, 0], entryDirection: [-1, 0] }), route({ start: [100, 0] })],
+      ]),
+    ).toEqual([0, 0]);
+  });
+
+  it("uses the exit and entry headings even when the endpoints coincide", () => {
+    const previous = route({ end: [0, 0] });
+    expect(
+      selectStripRouteCandidates([[previous], [route({ entryDirection: [-1, 0] }), route()]]),
+    ).toEqual([0, 1]);
+  });
+
+  it("optimizes the entire sequence instead of taking the locally closest start", () => {
+    const first = route({ end: [0, 0] });
+    const near = route({ start: [1, 0], end: [100, 0] });
+    const connected = route({ start: [2, 0], end: [5, 0] });
+    const last = route({ start: [6, 0] });
+    expect(selectStripRouteCandidates([[first], [near, connected], [last]])).toEqual([0, 1, 0]);
+  });
+
+  it("uses the takeoff point when selecting the first orientation", () => {
+    expect(selectStripRouteCandidates([[route({ start: [100, 0] }), route()]], [0, 0])).toEqual([
+      1,
+    ]);
+  });
+
+  it("handles coincident region endpoints without undefined directions", () => {
+    const groups = [[route({ end: [0, 0] })], [route(), route()]];
+    expect(selectStripRouteCandidates(groups, undefined, [[0, 0]])).toEqual([0, 0]);
+    expect(selectStripRouteCandidates([])).toEqual([]);
+  });
+
+  it("includes the final home leg only when the finish action requests it", () => {
+    const groups = [[route({ end: [100, 0], length: 100 }), route({ end: [1, 0], length: 101 })]];
+    expect(
+      selectStripRouteCandidates(groups, [0, 0], [], {
+        flightSpeed: 1,
+        transitSpeed: 1,
+        finishAction: "goHome",
+      }),
+    ).toEqual([1]);
+    for (const finishAction of ["noAction", "autoLand"] as const) {
+      expect(
+        selectStripRouteCandidates(groups, [0, 0], [], {
+          flightSpeed: 1,
+          transitSpeed: 1,
+          finishAction,
+        }),
+      ).toEqual([0]);
+    }
+  });
+
+  it("uses different survey and transit speeds instead of minimizing distance", () => {
+    const groups = [
+      [route({ end: [0, 0], length: 200 }), route({ start: [100, 0], end: [200, 0], length: 100 })],
+    ];
+    expect(
+      selectStripRouteCandidates(groups, [0, 0], [], {
+        flightSpeed: 1,
+        transitSpeed: 10,
+        finishAction: "noAction",
+      }),
+    ).toEqual([1]);
+    expect(
+      selectStripRouteCandidates(groups, [0, 0], [], {
+        flightSpeed: 1,
+        transitSpeed: 1,
+        finishAction: "noAction",
+      }),
+    ).toEqual([0]);
+  });
+
+  it("prefers the nearer entry when total flying times differ by at most two seconds", () => {
+    expect(
+      selectStripRouteCandidates(
+        [
+          [
+            route({ start: [100, 0], end: [200, 0], length: 100 }),
+            route({ start: [0, 0], end: [210, 0], length: 210 }),
+          ],
+        ],
+        [0, 0],
+        [],
+        { flightSpeed: 10, transitSpeed: 10, finishAction: "noAction" },
+      ),
+    ).toEqual([1]);
+  });
+
+  it("does not sacrifice a substantial time saving just to start closer", () => {
+    expect(
+      selectStripRouteCandidates(
+        [
+          [
+            route({ start: [100, 0], end: [200, 0], length: 100 }),
+            route({ start: [0, 0], end: [250, 0], length: 250 }),
+          ],
+        ],
+        [0, 0],
+        [],
+        { flightSpeed: 10, transitSpeed: 10, finishAction: "noAction" },
+      ),
+    ).toEqual([0]);
+  });
+
+  it("retains the nearer first entry after both paths reach the same later candidates", () => {
+    const groups = [
+      [
+        route({
+          start: [100, 0],
+          end: [0, 0],
+          entryDirection: [-1, 0],
+          exitDirection: [-1, 0],
+          length: 100,
+        }),
+        route({ end: [0, 0], length: 120 }),
+      ],
+      [route({ start: [0, 0], end: [100, 0], length: 100 })],
+      [route({ start: [100, 0], end: [200, 0], length: 100 })],
+    ];
+    expect(
+      selectStripRouteCandidates(groups, [0, 0], [], {
+        flightSpeed: 10,
+        transitSpeed: 100,
+        finishAction: "goHome",
+      }),
+    ).toEqual([1, 0, 0]);
+  });
+
+  it("applies the two-second tolerance once to the complete mission, not once per region", () => {
+    const groups = [[route({ end: [0, 0], length: 100 })]];
+    for (let index = 0; index < 4; index++)
+      groups.push([
+        route({ end: [0, 0], length: 100, entryDirection: [-1, 0], exitDirection: [-1, 0] }),
+        route({ end: [0, 0], length: 101.5 }),
+      ]);
+    const selected = selectStripRouteCandidates(groups);
+    const duration = groups.reduce((sum, group, index) => sum + group[selected[index]!]!.length, 0);
+    expect(duration).toBeLessThanOrEqual(502);
+  });
+
+  it("returns to the first waypoint without needing a takeoff reference", () => {
+    const groups = [[route({ end: [100, 0], length: 100 }), route({ end: [1, 0], length: 101 })]];
+    expect(
+      selectStripRouteCandidates(groups, undefined, [], {
+        flightSpeed: 1,
+        transitSpeed: 1,
+        finishAction: "gotoFirstWaypoint",
+      }),
+    ).toEqual([1]);
+    expect(
+      selectStripRouteCandidates(groups, undefined, [], {
+        flightSpeed: 1,
+        transitSpeed: 1,
+        finishAction: "goHome",
+      }),
+    ).toEqual([0]);
+  });
+
+  it("measures survey, ingress, between-region and finish legs with their respective speeds", () => {
+    const routes = [
+      route({ start: [10, 0], end: [30, 0], length: 20 }),
+      route({ start: [50, 0], end: [80, 0], length: 30 }),
+    ];
+    for (const [finishAction, distance, duration] of [
+      ["goHome", 160, 10.5],
+      ["noAction", 80, 6.5],
+      ["gotoFirstWaypoint", 150, 10],
+    ] as const) {
+      expect(
+        stripOrder.measureStripMission(routes, [0, 0], {
+          flightSpeed: 10,
+          transitSpeed: 20,
+          finishAction,
+        }),
+      ).toMatchObject({ distance, duration });
+    }
+  });
+
+  it("rejects invalid speeds instead of producing non-finite costs", () => {
+    for (const speed of [0, -1, NaN, Infinity]) {
+      expect(() =>
+        selectStripRouteCandidates([[route()]], [0, 0], [], {
+          flightSpeed: speed,
+          transitSpeed: 10,
+          finishAction: "goHome",
+        }),
+      ).toThrow();
+      expect(() =>
+        selectStripRouteCandidates([[route()]], [0, 0], [], {
+          flightSpeed: 10,
+          transitSpeed: speed,
+          finishAction: "goHome",
+        }),
+      ).toThrow();
+    }
+  });
+});

package/src/plan/strip-route-order.ts

@@ -0,0 +1,192 @@
+import type { EnuPoint } from "./geometry.js";
+import type { FinishAction } from "../types/enums.js";
+import { PlannerError } from "../types/errors.js";
+
+// Secondary route-shape preferences, never added to the estimated flying time.
+// A complete reversal costs 20 preference units; junction detours remain soft.
+const HEADING_COST_M = 10;
+const JUNCTION_DETOUR_WEIGHT = 0.5;
+const NEAR_EQUAL_TIME_S = 2;
+const TIME_EPS_S = 1e-8;
+
+const distance = (a: EnuPoint, b: EnuPoint) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+const headingChange = (a: EnuPoint, b: EnuPoint) =>
+  1 - Math.max(-1, Math.min(1, a[0] * b[0] + a[1] * b[1]));
+
+export interface StripRouteCandidate {
+  start: EnuPoint;
+  end: EnuPoint;
+  entryDirection: EnuPoint;
+  exitDirection: EnuPoint;
+  length: number;
+}
+
+export interface StripRouteTiming {
+  flightSpeed: number;
+  transitSpeed: number;
+  finishAction: FinishAction;
+}
+
+const DEFAULT_TIMING: StripRouteTiming = {
+  flightSpeed: 1,
+  transitSpeed: 1,
+  finishAction: "noAction",
+};
+
+function validateTiming(timing: StripRouteTiming): void {
+  if (
+    ![timing.flightSpeed, timing.transitSpeed].every((speed) => Number.isFinite(speed) && speed > 0)
+  )
+    throw new PlannerError(
+      "mappingStrip flight and transit speeds must be finite and greater than zero",
+    );
+}
+
+function finishDistance(
+  end: EnuPoint,
+  first: EnuPoint,
+  home: EnuPoint | undefined,
+  finish: FinishAction,
+): number {
+  const target = finish === "goHome" ? home : finish === "gotoFirstWaypoint" ? first : undefined;
+  return target ? distance(end, target) : 0;
+}
+
+/** Horizontal-flight estimate; vertical motion, wind and acceleration are not modeled. */
+export function measureStripMission(
+  routes: readonly Pick<StripRouteCandidate, "start" | "end" | "length">[],
+  home: EnuPoint | undefined,
+  timing: StripRouteTiming,
+): { distance: number; duration: number } {
+  validateTiming(timing);
+  if (routes.length === 0) return { distance: 0, duration: 0 };
+  const first = routes[0]!.start;
+  const workLength = routes.reduce((sum, route) => sum + route.length, 0);
+  let transitLength = home ? distance(home, first) : 0;
+  for (let index = 1; index < routes.length; index++)
+    transitLength += distance(routes[index - 1]!.end, routes[index]!.start);
+  transitLength += finishDistance(routes.at(-1)!.end, first, home, timing.finishAction);
+  return {
+    distance: workLength + transitLength,
+    duration: workLength / timing.flightSpeed + transitLength / timing.transitSpeed,
+  };
+}
+
+function transitionPreference(
+  previous: StripRouteCandidate,
+  next: StripRouteCandidate,
+  junction?: EnuPoint,
+): number {
+  const length = distance(previous.end, next.start);
+  const direction: EnuPoint | undefined =
+    length > 0.05
+      ? [(next.start[0] - previous.end[0]) / length, (next.start[1] - previous.end[1]) / length]
+      : undefined;
+  const turn = direction
+    ? headingChange(previous.exitDirection, direction) +
+      headingChange(direction, next.entryDirection)
+    : headingChange(previous.exitDirection, next.entryDirection);
+  const detour = junction
+    ? Math.max(0, distance(previous.end, junction) + distance(junction, next.start) - length)
+    : 0;
+  return HEADING_COST_M * turn + JUNCTION_DETOUR_WEIGHT * detour;
+}
+
+interface FinalChoice {
+  lastIndex: number;
+  time: number;
+  preference: number;
+  ingress: number;
+  back: number[][];
+}
+
+/** Optimize mission time, then favor nearer entries within a two-second total budget. */
+export function selectStripRouteCandidates(
+  groups: readonly (readonly StripRouteCandidate[])[],
+  home?: EnuPoint,
+  junctions: readonly EnuPoint[] = [],
+  timing: StripRouteTiming = DEFAULT_TIMING,
+): number[] {
+  if (groups.length === 0) return [];
+  validateTiming(timing);
+  if (groups.some((group) => group.length === 0))
+    throw new PlannerError("mappingStrip region has no route candidates");
+  const finals: FinalChoice[] = [];
+
+  // Keep each possible first entry separate. Otherwise a local near-equal-time
+  // tie can discard the globally fastest path or accumulate a tolerance per cut.
+  groups[0]!.forEach((first, firstIndex) => {
+    const ingress = home ? distance(home, first.start) : 0;
+    let times = groups[0]!.map((candidate, index) =>
+      index === firstIndex
+        ? candidate.length / timing.flightSpeed + ingress / timing.transitSpeed
+        : Infinity,
+    );
+    let preferences = groups[0]!.map((_, index) => (index === firstIndex ? 0 : Infinity));
+    const back = [groups[0]!.map(() => -1)];
+    for (let index = 1; index < groups.length; index++) {
+      const parents: number[] = [];
+      const nextPreferences: number[] = [];
+      const nextTimes = groups[index]!.map((candidate) => {
+        let bestTime = Infinity;
+        let bestPreference = Infinity;
+        let parent = 0;
+        groups[index - 1]!.forEach((previous, previousIndex) => {
+          const time =
+            times[previousIndex]! +
+            candidate.length / timing.flightSpeed +
+            distance(previous.end, candidate.start) / timing.transitSpeed;
+          const preference =
+            preferences[previousIndex]! +
+            transitionPreference(previous, candidate, junctions[index - 1]);
+          if (
+            time < bestTime - TIME_EPS_S ||
+            (Math.abs(time - bestTime) <= TIME_EPS_S && preference < bestPreference)
+          ) {
+            bestTime = time;
+            bestPreference = preference;
+            parent = previousIndex;
+          }
+        });
+        parents.push(parent);
+        nextPreferences.push(bestPreference);
+        return bestTime;
+      });
+      times = nextTimes;
+      preferences = nextPreferences;
+      back.push(parents);
+    }
+    groups.at(-1)!.forEach((last, lastIndex) => {
+      if (!Number.isFinite(times[lastIndex])) return;
+      finals.push({
+        lastIndex,
+        ingress,
+        back,
+        time:
+          times[lastIndex]! +
+          finishDistance(last.end, first.start, home, timing.finishAction) / timing.transitSpeed,
+        preference: preferences[lastIndex]!,
+      });
+    });
+  });
+  const fastest = Math.min(...finals.map((choice) => choice.time));
+  const close = finals.filter((choice) => choice.time <= fastest + NEAR_EQUAL_TIME_S + TIME_EPS_S);
+  const chosen = close.reduce((best, candidate) => {
+    if (candidate.ingress < best.ingress - 0.05) return candidate;
+    if (Math.abs(candidate.ingress - best.ingress) > 0.05) return best;
+    if (candidate.preference < best.preference - TIME_EPS_S) return candidate;
+    if (
+      Math.abs(candidate.preference - best.preference) <= TIME_EPS_S &&
+      candidate.time < best.time
+    )
+      return candidate;
+    return best;
+  });
+  let selected = chosen.lastIndex;
+  const result = groups.map(() => 0);
+  for (let index = groups.length - 1; index >= 0; index--) {
+    result[index] = selected;
+    selected = chosen.back[index]![selected]!;
+  }
+  return result;
+}

package/vite.config.ts

@@ -1,6 +1,13 @@
 import { defineConfig } from "vite-plus";
 
 export default defineConfig({
+  test: {
+    // Vitest v4 compatibility: preserve mock call history.
+    // Remove after tests no longer rely on calls from setup or earlier tests.
+    // https://viteplus.dev/guide/vitest-v5#remove-unneeded-compatibility-settings
+    // https://vitest.dev/guide/migration/#clearmocks-is-enabled-by-default
+    clearMocks: false,
+  },
   pack: {
     entry: ["src/index.ts"],
     format: "esm",