@lumikmz/kmz 0.2.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@lumikmz/kmz",
+  "version": "0.2.0",
+  "description": "DJI KMZ/WPML domain model + plan() algorithm + validate(), spec-aligned types mirroring docs/kmz/",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "vite-plus": "latest",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@^0.1.20"
+  },
+  "scripts": {
+    "build": "vp pack"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./types/index.js";
+export { plan } from "./plan/index.js";
+export { validate } from "./validate/index.js";

package/src/plan/geometry.ts

@@ -0,0 +1,109 @@
+import type { LngLat } from "../types/branded.js";
+
+const EARTH_RADIUS = 6_371_000;
+const DEG2RAD = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+
+export type EnuPoint = readonly [number, number];
+
+/** Project lng/lat to local ENU meters around `origin`. */
+export function lngLatToEnu(point: LngLat, origin: LngLat): EnuPoint {
+  const dLat = (point.lat - origin.lat) * DEG2RAD;
+  const dLng = (point.lng - origin.lng) * DEG2RAD;
+  const avgLat = ((point.lat + origin.lat) / 2) * DEG2RAD;
+  return [dLng * EARTH_RADIUS * Math.cos(avgLat), dLat * EARTH_RADIUS];
+}
+
+/** Inverse of `lngLatToEnu`. */
+export function enuToLngLat([x, y]: EnuPoint, origin: LngLat): LngLat {
+  const avgLat = origin.lat * DEG2RAD;
+  return {
+    lng: origin.lng + (x / (EARTH_RADIUS * Math.cos(avgLat))) * RAD2DEG,
+    lat: origin.lat + (y / EARTH_RADIUS) * RAD2DEG,
+  };
+}
+
+export function centroid(points: readonly LngLat[]): LngLat {
+  let sumLng = 0;
+  let sumLat = 0;
+  for (const p of points) {
+    sumLng += p.lng;
+    sumLat += p.lat;
+  }
+  return { lng: sumLng / points.length, lat: sumLat / points.length };
+}
+
+/**
+ * Bearing from `from` → `to` in degrees clockwise from North.
+ * ENU axes: x=east, y=north.
+ */
+export function bearingDeg(from: EnuPoint, to: EnuPoint): number {
+  return Math.atan2(to[0] - from[0], to[1] - from[1]) * RAD2DEG;
+}
+
+/** Clip a horizontal scan line `y = const` against a polygon; returns `[x_enter, x_exit]` pairs. */
+function clipHorizontal(y: number, polygon: readonly EnuPoint[]): [number, number][] {
+  const intersections: number[] = [];
+  const n = polygon.length;
+  for (let i = 0; i < n; i++) {
+    const [x1, y1] = polygon[i]!;
+    const [x2, y2] = polygon[(i + 1) % n]!;
+    if ((y1 <= y && y < y2) || (y2 <= y && y < y1)) {
+      const t = (y - y1) / (y2 - y1);
+      intersections.push(x1 + t * (x2 - x1));
+    }
+  }
+  intersections.sort((a, b) => a - b);
+  const out: [number, number][] = [];
+  for (let i = 0; i + 1 < intersections.length; i += 2) {
+    out.push([intersections[i]!, intersections[i + 1]!]);
+  }
+  return out;
+}
+
+/** Serpentine boustrophedon scan over a polygon; returns ENU waypoints. */
+export function scanWaypoints(polygon: readonly EnuPoint[], lineSpacing: number): EnuPoint[] {
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (const [, y] of polygon) {
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+  }
+
+  const waypoints: EnuPoint[] = [];
+  let leftToRight = true;
+  for (let y = minY; y <= maxY + lineSpacing * 0.5; y += lineSpacing) {
+    const segments = clipHorizontal(y, polygon);
+    for (const [x1, x2] of segments) {
+      if (leftToRight) {
+        waypoints.push([x1, y], [x2, y]);
+      } else {
+        waypoints.push([x2, y], [x1, y]);
+      }
+    }
+    leftToRight = !leftToRight;
+  }
+  return waypoints;
+}
+
+/**
+ * Parse a KML coordinates string like `"lon,lat lon,lat lon,lat"` or `"lon,lat,alt ..."`
+ * into LngLat array (altitude dropped).
+ */
+export function parseCoordinatesString(s: string): LngLat[] {
+  return s
+    .trim()
+    .split(/\s+/)
+    .map((tuple) => {
+      const [lng, lat] = tuple.split(",").map(Number) as [number, number];
+      return { lng, lat };
+    });
+}
+
+/** Encode a polygon ring back to `"lon,lat,alt lon,lat,alt"` format (alt defaults to 0). */
+export function encodePolygonCoordinates(
+  ring: readonly LngLat[],
+  altitudeMeters: number = 0,
+): string {
+  return ring.map((p) => `${p.lng},${p.lat},${altitudeMeters}`).join(" ");
+}

package/src/plan/index.ts

@@ -0,0 +1,31 @@
+import { PlannerError } from "../types/errors.js";
+import type {
+  Mapping2dTemplate,
+  Mapping3dTemplate,
+  MappingStripTemplate,
+  Template,
+  WaypointTemplate,
+} from "../types/template.js";
+import type { Waylines } from "../types/waylines.js";
+import { planMapping2d } from "./plan-mapping2d.js";
+import { planMapping3d } from "./plan-mapping3d.js";
+import { planMappingStrip } from "./plan-mapping-strip.js";
+import { planWaypoint } from "./plan-waypoint.js";
+
+const isWaypoint = (t: Template): t is WaypointTemplate => t.Folder.templateType === "waypoint";
+const isMapping2d = (t: Template): t is Mapping2dTemplate => t.Folder.templateType === "mapping2d";
+const isMapping3d = (t: Template): t is Mapping3dTemplate => t.Folder.templateType === "mapping3d";
+const isMappingStrip = (t: Template): t is MappingStripTemplate =>
+  t.Folder.templateType === "mappingStrip";
+
+/**
+ * Compile a high-level `Template` into executable `Waylines`.
+ * Dispatch is by `template.Folder.templateType` per the DJI WPML spec.
+ */
+export function plan(template: Template): Waylines {
+  if (isWaypoint(template)) return planWaypoint(template);
+  if (isMapping2d(template)) return planMapping2d(template);
+  if (isMapping3d(template)) return planMapping3d(template);
+  if (isMappingStrip(template)) return planMappingStrip(template);
+  throw new PlannerError(`Unknown templateType: ${(template as Template).Folder.templateType}`);
+}

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

@@ -0,0 +1,84 @@
+import { degrees } from "../types/branded.js";
+import type { ExecuteHeightMode } from "../types/enums.js";
+import type { MappingStripFolder, MappingStripTemplate } from "../types/template.js";
+import type { Waylines, WaylinesFolder } from "../types/waylines.js";
+import type { WaylinesPlacemark } from "../types/placemark.js";
+import { bearingDeg, centroid, lngLatToEnu } from "./geometry.js";
+
+/**
+ * Compile a `mappingStrip` template into a single wayline that follows the
+ * supplied LineString. Each LineString vertex becomes one waypoint.
+ *
+ * When `stripUseTemplateAltitude` is true the altitude in each LineString
+ * triple is used as the executeHeight; otherwise the folder's `height` is used.
+ */
+export function planMappingStrip(template: MappingStripTemplate): Waylines {
+  const folder = template.Folder;
+  const coords = parseTriples(folder.Placemark.LineString.coordinates);
+  const origin = centroid(coords.map((c) => ({ lng: c.lng, lat: c.lat })));
+  const enuPath = coords.map((c) => lngLatToEnu({ lng: c.lng, lat: c.lat }, origin));
+
+  const placemarks: WaylinesPlacemark[] = coords.map((c, index) => {
+    const isLast = index === coords.length - 1;
+    const headingAngle = isLast ? 0 : bearingDeg(enuPath[index]!, enuPath[index + 1]!);
+    const executeHeight =
+      folder.stripUseTemplateAltitude && c.alt !== undefined
+        ? (c.alt as ReturnType<typeof folder.height extends infer T ? () => T : never>)
+        : folder.height;
+
+    return {
+      Point: { coordinates: { lng: c.lng, lat: c.lat } },
+      index,
+      executeHeight,
+      waypointSpeed: folder.autoFlightSpeed,
+      waypointHeadingParam: {
+        waypointHeadingMode: "followWayline",
+        waypointHeadingAngle: degrees(headingAngle),
+        waypointHeadingPathMode: "followBadArc",
+      },
+      waypointTurnParam: { waypointTurnMode: "toPointAndPassWithContinuityCurvature" },
+    };
+  });
+
+  const waylineFolder: WaylinesFolder = {
+    templateId: folder.templateId,
+    waylineId: 0,
+    executeHeightMode: heightModeToExecuteMode(folder),
+    autoFlightSpeed: folder.autoFlightSpeed,
+    Placemark: placemarks,
+  };
+
+  return { missionConfig: template.missionConfig, Folder: [waylineFolder] };
+}
+
+interface Triple {
+  lng: number;
+  lat: number;
+  alt?: number;
+}
+
+function parseTriples(s: string): Triple[] {
+  return s
+    .trim()
+    .split(/\s+/)
+    .map((tuple) => {
+      const parts = tuple.split(",").map(Number);
+      return {
+        lng: parts[0]!,
+        lat: parts[1]!,
+        ...(parts[2] !== undefined ? { alt: parts[2]! } : {}),
+      };
+    });
+}
+
+function heightModeToExecuteMode(folder: MappingStripFolder): ExecuteHeightMode {
+  switch (folder.waylineCoordinateSysParam.heightMode) {
+    case "EGM96":
+      return "WGS84";
+    case "relativeToStartPoint":
+      return "relativeToStartPoint";
+    case "aboveGroundLevel":
+    case "realTimeFollowSurface":
+      return "realTimeFollowSurface";
+  }
+}

package/src/plan/plan-mapping2d.ts

@@ -0,0 +1,128 @@
+import { degrees, metersPerSecond } from "../types/branded.js";
+import type { ActionGroup } from "../types/action.js";
+import type { ExecuteHeightMode } from "../types/enums.js";
+import type { Mapping2dTemplate, Mapping2dFolder } from "../types/template.js";
+import type { Waylines, WaylinesFolder } from "../types/waylines.js";
+import type { WaylinesPlacemark } from "../types/placemark.js";
+import {
+  bearingDeg,
+  centroid,
+  enuToLngLat,
+  lngLatToEnu,
+  parseCoordinatesString,
+  scanWaypoints,
+} from "./geometry.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 {
+  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 lngLatWps = enuWps.map((p) => enuToLngLat(p, origin));
+
+  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]!);
+
+    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,
+                },
+              },
+            ],
+          },
+        ];
+
+    return {
+      Point: { coordinates: coord },
+      index,
+      executeHeight: folder.height,
+      waypointSpeed: folder.autoFlightSpeed,
+      waypointHeadingParam: {
+        waypointHeadingMode: "followWayline",
+        waypointHeadingAngle: degrees(headingAngle),
+        waypointHeadingPathMode: "followBadArc",
+      },
+      waypointTurnParam: { waypointTurnMode: "toPointAndPassWithContinuityCurvature" },
+      ...(actionGroup.length > 0 ? { actionGroup } : {}),
+    };
+  });
+
+  const waylineFolder: WaylinesFolder = {
+    templateId: folder.templateId,
+    waylineId: 0,
+    executeHeightMode: heightModeToExecuteMode(folder),
+    autoFlightSpeed: folder.autoFlightSpeed,
+    startActionGroup: {
+      actionGroupId: 65535,
+      actionGroupStartIndex: 0,
+      actionGroupEndIndex: 0,
+      actionGroupMode: "sequence",
+      actionTrigger: { actionTriggerType: "reachPoint" },
+      action: [
+        {
+          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,
+          },
+        },
+      ],
+    },
+    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";
+  }
+}
+
+// Suppress unused import warnings for re-exports
+void metersPerSecond;

package/src/plan/plan-mapping3d.ts

@@ -0,0 +1,188 @@
+import { degrees } from "../types/branded.js";
+import type { Action, ActionGroup, GimbalRotateAction } from "../types/action.js";
+import type { ExecuteHeightMode } 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 {
+  centroid,
+  enuToLngLat,
+  type EnuPoint,
+  lngLatToEnu,
+  parseCoordinatesString,
+  scanWaypoints,
+} from "./geometry.js";
+
+const DEFAULT_HFOV_DEG = 84;
+
+/**
+ * Compile a `mapping3d` (oblique photography) template into 5 waylines:
+ * one nadir (ortho) pass + four oblique passes (front/back/left/right).
+ */
+export function planMapping3d(template: Mapping3dTemplate): Waylines {
+  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,
+    ),
+  );
+
+  return { missionConfig: template.missionConfig, Folder };
+}
+
+function buildObliquePass(
+  folder: Mapping3dFolder,
+  waylineId: number,
+  origin: { lng: number; lat: number },
+  enuWps: readonly EnuPoint[],
+  headingAngle: number,
+  gimbalPitch: number,
+  minShootInterval: number,
+): WaylinesFolder {
+  const lastIndex = enuWps.length - 1;
+
+  const placemarks: WaylinesPlacemark[] = enuWps.map((enu, index) => {
+    const coord = enuToLngLat(enu, origin);
+    const placemark: WaylinesPlacemark = {
+      Point: { coordinates: coord },
+      index,
+      executeHeight: folder.height,
+      waypointSpeed: folder.autoFlightSpeed,
+      waypointHeadingParam: {
+        waypointHeadingMode: "fixed",
+        waypointHeadingAngle: degrees(headingAngle),
+        waypointHeadingPathMode: "followBadArc",
+      },
+      waypointTurnParam: { waypointTurnMode: "toPointAndPassWithContinuityCurvature" },
+    };
+
+    const groups = waypointActionGroups(index, lastIndex, gimbalPitch, minShootInterval);
+    if (groups.length > 0) placemark.actionGroup = groups;
+    return placemark;
+  });
+
+  return {
+    templateId: folder.templateId,
+    waylineId,
+    executeHeightMode: heightModeToExecuteMode(folder.waylineCoordinateSysParam.heightMode),
+    autoFlightSpeed: folder.autoFlightSpeed,
+    startActionGroup: startGimbalRotateGroup(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 {
+  return {
+    actionId,
+    actionActuatorFunc: "gimbalRotate",
+    actionActuatorFuncParam: {
+      payloadPositionIndex: 0,
+      gimbalHeadingYawBase: "north",
+      gimbalRotateMode: "absoluteAngle",
+      gimbalPitchRotateEnable: true,
+      gimbalPitchRotateAngle: degrees(pitch),
+      gimbalRollRotateEnable: false,
+      gimbalRollRotateAngle: degrees(0),
+      gimbalYawRotateEnable: false,
+      gimbalYawRotateAngle: degrees(0),
+      gimbalRotateTimeEnable: false,
+      gimbalRotateTime: 0,
+    },
+  };
+}
+
+function takePhoto(actionId: number): Action {
+  return {
+    actionId,
+    actionActuatorFunc: "takePhoto",
+    actionActuatorFuncParam: {
+      payloadPositionIndex: 0,
+      payloadLensIndex: ["wide"],
+      useGlobalPayloadLensIndex: false,
+    },
+  };
+}
+
+function heightModeToExecuteMode(
+  mode: Mapping3dFolder["waylineCoordinateSysParam"]["heightMode"],
+): ExecuteHeightMode {
+  switch (mode) {
+    case "EGM96":
+      return "WGS84";
+    case "relativeToStartPoint":
+      return "relativeToStartPoint";
+    case "aboveGroundLevel":
+    case "realTimeFollowSurface":
+      return "realTimeFollowSurface";
+  }
+}

package/src/plan/plan-waypoint.ts

@@ -0,0 +1,80 @@
+import { degrees } from "../types/branded.js";
+import type { ActionGroup } from "../types/action.js";
+import type { ExecuteHeightMode } from "../types/enums.js";
+import type { WaypointTemplate, WaypointFolder } from "../types/template.js";
+import type { Waylines, WaylinesFolder } from "../types/waylines.js";
+import type { WaylinesPlacemark } from "../types/placemark.js";
+import type { WaypointHeadingParam, WaypointTurnParam } from "../types/waypoint-params.js";
+
+/**
+ * Compile a `waypoint` template directly: each Placemark in the template becomes
+ * one waypoint in the wayline, resolving `useGlobalXxx` flags against folder defaults.
+ */
+export function planWaypoint(template: WaypointTemplate): Waylines {
+  const folder: WaypointFolder = template.Folder;
+
+  const placemarks: WaylinesPlacemark[] = folder.Placemark.map((p, i) => {
+    const heading: WaypointHeadingParam =
+      p.useGlobalHeadingParam || p.waypointHeadingParam === undefined
+        ? folder.globalWaypointHeadingParam
+        : p.waypointHeadingParam;
+
+    const turn: WaypointTurnParam =
+      p.useGlobalTurnParam || p.waypointTurnParam === undefined
+        ? { waypointTurnMode: folder.globalWaypointTurnMode }
+        : p.waypointTurnParam;
+
+    const executeHeight =
+      p.useGlobalHeight || p.height === undefined ? folder.globalHeight : p.height;
+
+    const waypointSpeed =
+      p.useGlobalSpeed || p.waypointSpeed === undefined ? folder.autoFlightSpeed : p.waypointSpeed;
+
+    const placemark: WaylinesPlacemark = {
+      Point: p.Point,
+      index: i,
+      executeHeight,
+      waypointSpeed,
+      waypointHeadingParam: heading,
+      waypointTurnParam: turn,
+      ...(p.useStraightLine !== undefined ? { useStraightLine: p.useStraightLine } : {}),
+      ...(p.isRisky !== undefined ? { isRisky: p.isRisky } : {}),
+      ...(p.actionGroup !== undefined ? { actionGroup: p.actionGroup } : {}),
+    };
+    return placemark;
+  });
+
+  const waylineFolder: WaylinesFolder = {
+    templateId: folder.templateId,
+    waylineId: 0,
+    executeHeightMode: heightModeToExecuteMode(folder.waylineCoordinateSysParam.heightMode),
+    autoFlightSpeed: folder.autoFlightSpeed,
+    Placemark: placemarks,
+  };
+
+  return { missionConfig: template.missionConfig, Folder: [waylineFolder] };
+}
+
+/**
+ * Map a template heightMode to a waylines executeHeightMode.
+ * - `EGM96` → `WGS84` (waylines spec doesn't expose EGM96; runtime resolves it).
+ * - `aboveGroundLevel` → `realTimeFollowSurface` (closest executable analog).
+ */
+function heightModeToExecuteMode(
+  mode: WaypointFolder["waylineCoordinateSysParam"]["heightMode"],
+): ExecuteHeightMode {
+  switch (mode) {
+    case "EGM96":
+      return "WGS84";
+    case "relativeToStartPoint":
+      return "relativeToStartPoint";
+    case "aboveGroundLevel":
+    case "realTimeFollowSurface":
+      return "realTimeFollowSurface";
+  }
+}
+
+// Re-export degrees so dependent algorithms can use it consistently.
+export { degrees };
+// Re-export ActionGroup so we don't need to import it across plan files.
+export type { ActionGroup };