@lumikmz/kmz 0.2.0

package/src/types/placemark.ts

@@ -0,0 +1,96 @@
+import type { Degrees, LngLat, Meters, MetersPerSecond } from "./branded.js";
+import type { ActionGroup } from "./action.js";
+import type { ExecuteHeightMode } from "./enums.js";
+import type { WaypointHeadingParam, WaypointTurnParam } from "./waypoint-params.js";
+
+// ─── Template Placemark ──────────────────────────────────────────────────────
+
+/**
+ * `Placemark` inside a `waypoint`-type Folder of template.kml.
+ *
+ * Note coordinate order: `Point.coordinates` is `lon,lat` per KML (no altitude).
+ */
+export interface TemplateWaypointPlacemark {
+  Point: { coordinates: LngLat };
+  index: number;
+
+  useGlobalHeight: boolean;
+  /** Required iff `useGlobalHeight === false`. WGS84 ellipsoid. */
+  ellipsoidHeight?: Meters;
+  /** Required iff `useGlobalHeight === false`. Interpretation per Folder `heightMode`. */
+  height?: Meters;
+
+  useGlobalSpeed: boolean;
+  /** Required iff `useGlobalSpeed === false`. Range `[1, 15]`. */
+  waypointSpeed?: MetersPerSecond;
+
+  useGlobalHeadingParam: boolean;
+  /** Required iff `useGlobalHeadingParam === false`. */
+  waypointHeadingParam?: WaypointHeadingParam;
+
+  useGlobalTurnParam: boolean;
+  /** Required iff `useGlobalTurnParam === false`. */
+  waypointTurnParam?: WaypointTurnParam;
+
+  /**
+   * Required iff inner `waypointTurnMode` is one of
+   * `toPointAndStopWithContinuityCurvature` or `toPointAndPassWithContinuityCurvature`.
+   */
+  useStraightLine?: boolean;
+
+  /** Required iff Folder `gimbalPitchMode === "usePointSetting"`. */
+  gimbalPitchAngle?: Degrees;
+
+  /** Optional on M30/M30T, M3D/M3TD, M4D/M4TD, M4E/M4T. */
+  isRisky?: boolean;
+
+  actionGroup?: ActionGroup[];
+}
+
+/**
+ * `Placemark` inside a mapping-type Folder (mapping2d / mapping3d).
+ * Holds the survey polygon. Folder-level fields carry shooting params.
+ */
+export interface TemplatePolygonPlacemark {
+  Polygon: {
+    outerBoundaryIs: {
+      LinearRing: {
+        /** Space-separated `lon,lat,alt` triples. */
+        coordinates: string;
+      };
+    };
+  };
+}
+
+/** Placemark for `mappingStrip` Folder — uses a LineString. */
+export interface TemplateLineStringPlacemark {
+  LineString: {
+    /** Space-separated `lon,lat,alt` triples. Alt consumed only when `stripUseTemplateAltitude === true`. */
+    coordinates: string;
+  };
+}
+
+// ─── Waylines Placemark ──────────────────────────────────────────────────────
+
+/**
+ * `Placemark` inside a Folder of waylines.wpml.
+ *
+ * The spec's `useGlobalXxx` switches are template-only — in waylines.wpml the
+ * params are inlined unconditionally, so they are required here.
+ */
+export interface WaylinesPlacemark {
+  Point: { coordinates: LngLat };
+  index: number;
+  /** Interpretation per Folder `executeHeightMode`. */
+  executeHeight: Meters;
+  /** Range `[1, 15]`. */
+  waypointSpeed: MetersPerSecond;
+  waypointHeadingParam: WaypointHeadingParam;
+  waypointTurnParam: WaypointTurnParam;
+  useStraightLine?: boolean;
+  isRisky?: boolean;
+  actionGroup?: ActionGroup[];
+}
+
+/** Re-export for convenience; folder-level executeHeightMode lives here. */
+export type { ExecuteHeightMode };

package/src/types/template.ts

@@ -0,0 +1,170 @@
+import type { Degrees, Meters, MetersPerSecond } from "./branded.js";
+import type { MissionConfig, PayloadParam } from "./mission-config.js";
+import type { GimbalPitchMode, ShootType, WaypointTurnMode } from "./enums.js";
+import type {
+  MappingHeadingParam,
+  Overlap,
+  WaylineCoordinateSysParam,
+  WaypointHeadingParam,
+} from "./waypoint-params.js";
+import type {
+  TemplateLineStringPlacemark,
+  TemplatePolygonPlacemark,
+  TemplateWaypointPlacemark,
+} from "./placemark.js";
+
+/**
+ * `template.kml` document. Mirrors `<kml><Document>` structure.
+ * See `docs/kmz/template-kml.html`.
+ */
+export type Template =
+  | WaypointTemplate
+  | Mapping2dTemplate
+  | Mapping3dTemplate
+  | MappingStripTemplate;
+
+interface TemplateDocumentBase {
+  /** Unix milliseconds. */
+  author?: string;
+  createTime?: number;
+  updateTime?: number;
+  missionConfig: MissionConfig;
+}
+
+// ─── waypoint ────────────────────────────────────────────────────────────────
+
+export interface WaypointTemplate extends TemplateDocumentBase {
+  Folder: WaypointFolder;
+}
+
+export interface WaypointFolder {
+  templateType: "waypoint";
+  /** Range `[0, 65535]`. */
+  templateId: number;
+  waylineCoordinateSysParam: WaylineCoordinateSysParam;
+  /** Range `[1, 15]` m/s. */
+  autoFlightSpeed: MetersPerSecond;
+  payloadParam?: PayloadParam;
+
+  globalWaypointTurnMode: WaypointTurnMode;
+  /**
+   * Required iff `globalWaypointTurnMode` is one of
+   * `toPointAndStopWithContinuityCurvature` or `toPointAndPassWithContinuityCurvature`.
+   */
+  globalUseStraightLine?: boolean;
+  /** `manual` | `usePointSetting`. */
+  gimbalPitchMode: GimbalPitchMode;
+  /** Relative to takeoff point. */
+  globalHeight: Meters;
+  globalWaypointHeadingParam: WaypointHeadingParam;
+
+  Placemark: TemplateWaypointPlacemark[];
+}
+
+// ─── mapping2d ───────────────────────────────────────────────────────────────
+
+export interface Mapping2dTemplate extends TemplateDocumentBase {
+  Folder: Mapping2dFolder;
+}
+
+export interface Mapping2dFolder {
+  templateType: "mapping2d";
+  templateId: number;
+  waylineCoordinateSysParam: WaylineCoordinateSysParam;
+  autoFlightSpeed: MetersPerSecond;
+  payloadParam?: PayloadParam;
+
+  /** M300/M350 only. */
+  caliFlightEnable?: boolean;
+  elevationOptimizeEnable: boolean;
+  /** M300/M350+P1, M3E/M3T/M3M, M3D. */
+  smartObliqueEnable?: boolean;
+  smartObliqueGimbalPitch?: Degrees;
+
+  shootType: ShootType;
+  /** `[0, 360]`. */
+  direction: Degrees;
+  /** Outward survey-area margin, meters. */
+  margin: number;
+  overlap: Overlap;
+  /** WGS84 ellipsoid. */
+  ellipsoidHeight: Meters;
+  /** Per Folder `heightMode`. */
+  height: Meters;
+
+  /** M3E/M3T/M3M. */
+  facadeWaylineEnable?: boolean;
+
+  /** M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T. */
+  mappingHeadingParam?: MappingHeadingParam;
+  /** M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T. */
+  gimbalPitchMode?: "manual" | "fixed";
+  /** Required iff `gimbalPitchMode === "fixed"`. `[-90, -30]`. */
+  gimbalPitchAngle?: Degrees;
+  /** M4E only. */
+  quickOrthoMappingEnable?: boolean;
+  /** Required iff `quickOrthoMappingEnable === true`. `[10, 30]`. */
+  quickOrthoMappingPitch?: Degrees;
+
+  Placemark: TemplatePolygonPlacemark;
+}
+
+// ─── mapping3d (oblique photography) ─────────────────────────────────────────
+
+export interface Mapping3dTemplate extends TemplateDocumentBase {
+  Folder: Mapping3dFolder;
+}
+
+export interface Mapping3dFolder {
+  templateType: "mapping3d";
+  templateId: number;
+  waylineCoordinateSysParam: WaylineCoordinateSysParam;
+  autoFlightSpeed: MetersPerSecond;
+  payloadParam?: PayloadParam;
+
+  caliFlightEnable?: boolean;
+  inclinedGimbalPitch: Degrees;
+  /** Range `[1, 15]`. */
+  inclinedFlightSpeed: MetersPerSecond;
+  shootType: ShootType;
+  direction: Degrees;
+  margin: number;
+  overlap: Overlap;
+  ellipsoidHeight: Meters;
+  height: Meters;
+
+  Placemark: TemplatePolygonPlacemark;
+}
+
+// ─── mappingStrip ────────────────────────────────────────────────────────────
+
+export interface MappingStripTemplate extends TemplateDocumentBase {
+  Folder: MappingStripFolder;
+}
+
+export interface MappingStripFolder {
+  templateType: "mappingStrip";
+  templateId: number;
+  waylineCoordinateSysParam: WaylineCoordinateSysParam;
+  autoFlightSpeed: MetersPerSecond;
+  payloadParam?: PayloadParam;
+
+  caliFlightEnable: boolean;
+  shootType: ShootType;
+  direction: Degrees;
+  /** Float meters (vs integer in mapping2d/3d). */
+  margin: number;
+  singleLineEnable: boolean;
+  cuttingDistance: number;
+  boundaryOptimEnable: boolean;
+  leftExtend: number;
+  rightExtend: number;
+  includeCenterEnable: boolean;
+  overlap: Overlap;
+  ellipsoidHeight: Meters;
+  height: Meters;
+  /** When true, altitudes are read from LineString triples. */
+  stripUseTemplateAltitude: boolean;
+
+  Placemark: TemplateLineStringPlacemark;
+}

package/src/types/waylines.ts

@@ -0,0 +1,32 @@
+import type { MetersPerSecond } from "./branded.js";
+import type { ActionGroup } from "./action.js";
+import type { ExecuteHeightMode } from "./enums.js";
+import type { MissionConfig } from "./mission-config.js";
+import type { WaylinesPlacemark } from "./placemark.js";
+
+/**
+ * `waylines.wpml` document. Mirrors `<kml><Document>` structure.
+ * See `docs/kmz/waylines-wpml.html`.
+ *
+ * Cardinality: `Folder` is `1..*` — `mapping3d` templates expand to 5 Folders
+ * (1 ortho + 4 oblique).
+ */
+export interface Waylines {
+  missionConfig: MissionConfig;
+  Folder: WaylinesFolder[];
+}
+
+export interface WaylinesFolder {
+  /** Links back to template Folder's `templateId`. */
+  templateId: number;
+  waylineId: number;
+  executeHeightMode: ExecuteHeightMode;
+  /** Range `[1, 15]`. */
+  autoFlightSpeed: MetersPerSecond;
+  /**
+   * Optional pre-wayline action group.
+   * Available on M30/M30T, M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T.
+   */
+  startActionGroup?: ActionGroup;
+  Placemark: WaylinesPlacemark[];
+}

package/src/types/waypoint-params.ts

@@ -0,0 +1,78 @@
+import type { Degrees, LngLatHeight, Meters } from "./branded.js";
+import type {
+  CoordinateMode,
+  MappingHeadingMode,
+  PositioningType,
+  TemplateHeightMode,
+  WaypointHeadingMode,
+  WaypointHeadingPathMode,
+  WaypointTurnMode,
+} from "./enums.js";
+
+/**
+ * `wpml:waypointHeadingParam` & `wpml:globalWaypointHeadingParam`.
+ * See `docs/kmz/common-element.html` §waypointHeadingParam.
+ */
+export interface WaypointHeadingParam {
+  waypointHeadingMode: WaypointHeadingMode;
+  /** Required iff `waypointHeadingMode === "smoothTransition"`. Range `[-180, 180]`. */
+  waypointHeadingAngle?: Degrees;
+  /** Required iff `waypointHeadingMode === "towardPOI"`. Z aim unsupported; set height to 0. */
+  waypointPoiPoint?: LngLatHeight;
+  waypointHeadingPathMode: WaypointHeadingPathMode;
+}
+
+/**
+ * `wpml:waypointTurnParam`.
+ * See `docs/kmz/common-element.html` §waypointTurnParam.
+ */
+export interface WaypointTurnParam {
+  waypointTurnMode: WaypointTurnMode;
+  /**
+   * Required iff `waypointTurnMode === "coordinateTurn"`
+   * OR (`waypointTurnMode === "toPointAndPassWithContinuityCurvature"` AND useStraightLine = 1).
+   */
+  waypointTurnDampingDist?: Meters;
+}
+
+/**
+ * `wpml:waylineCoordinateSysParam`.
+ * Mapping templates require globalShootHeight + surfaceFollowModeEnable.
+ */
+export interface WaylineCoordinateSysParam {
+  /** Currently only `"WGS84"` is allowed. */
+  coordinateMode: CoordinateMode;
+  heightMode: TemplateHeightMode;
+  positioningType?: PositioningType;
+  /** Required for mapping templates. */
+  globalShootHeight?: Meters;
+  /** Required for mapping templates. */
+  surfaceFollowModeEnable?: boolean;
+  /** Required iff `surfaceFollowModeEnable === true`. */
+  surfaceRelativeHeight?: Meters;
+}
+
+/**
+ * `wpml:mappingHeadingParam` — only on `mapping2d` Folder
+ * (M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T).
+ */
+export interface MappingHeadingParam {
+  mappingHeadingMode: MappingHeadingMode;
+  /** Required iff `mappingHeadingMode === "fixed"`. Range `[0, 360]`. */
+  mappingHeadingAngle?: Degrees;
+}
+
+/**
+ * `wpml:overlap` — child of mapping2d / mapping3d / mappingStrip Folders.
+ * All fields individually optional in spec but at least one ortho pair is required in practice.
+ */
+export interface Overlap {
+  orthoLidarOverlapH?: number;
+  orthoLidarOverlapW?: number;
+  orthoCameraOverlapH?: number;
+  orthoCameraOverlapW?: number;
+  inclinedLidarOverlapH?: number;
+  inclinedLidarOverlapW?: number;
+  inclinedCameraOverlapH?: number;
+  inclinedCameraOverlapW?: number;
+}

package/src/validate/index.ts

@@ -0,0 +1,25 @@
+import type { Issue } from "../types/errors.js";
+import type { Template } from "../types/template.js";
+import type { Waylines } from "../types/waylines.js";
+import { validateMissionConfig } from "./validate-mission-config.js";
+import { validateTemplate } from "./validate-template.js";
+import { validateWaylines } from "./validate-waylines.js";
+
+export type { Issue } from "../types/errors.js";
+
+/**
+ * Run semantic checks against a `Template` or `Waylines` document.
+ * Returns a list of issues (`severity: "error" | "warning"`). Empty array = valid.
+ *
+ * The function is non-throwing by design — callers decide how to react.
+ */
+export function validate(doc: Template | Waylines): Issue[] {
+  const issues: Issue[] = [];
+  issues.push(...validateMissionConfig(doc.missionConfig, "missionConfig"));
+  if ("Folder" in doc && Array.isArray(doc.Folder)) {
+    issues.push(...validateWaylines(doc as Waylines));
+  } else {
+    issues.push(...validateTemplate(doc as Template));
+  }
+  return issues;
+}

package/src/validate/validate-mission-config.ts

@@ -0,0 +1,48 @@
+import type { Issue } from "../types/errors.js";
+import type { MissionConfig } from "../types/mission-config.js";
+
+export function validateMissionConfig(config: MissionConfig, path: string): Issue[] {
+  const issues: Issue[] = [];
+
+  if (config.exitOnRCLost === "executeLostAction" && config.executeRCLostAction === undefined) {
+    issues.push({
+      path: `${path}.executeRCLostAction`,
+      message: "executeRCLostAction is required when exitOnRCLost === 'executeLostAction'",
+      severity: "error",
+    });
+  }
+
+  if (config.globalTransitionalSpeed < 1 || config.globalTransitionalSpeed > 15) {
+    issues.push({
+      path: `${path}.globalTransitionalSpeed`,
+      message: `globalTransitionalSpeed must be in [1,15] m/s, got ${config.globalTransitionalSpeed}`,
+      severity: "error",
+    });
+  }
+
+  if (config.globalRTHHeight < 2 || config.globalRTHHeight > 1500) {
+    issues.push({
+      path: `${path}.globalRTHHeight`,
+      message: `globalRTHHeight must be in [2,1500] m, got ${config.globalRTHHeight}`,
+      severity: "error",
+    });
+  }
+
+  if (config.takeOffSecurityHeight < 1.2 || config.takeOffSecurityHeight > 1500) {
+    issues.push({
+      path: `${path}.takeOffSecurityHeight`,
+      message: `takeOffSecurityHeight must be in [1.2,1500] m, got ${config.takeOffSecurityHeight}`,
+      severity: "error",
+    });
+  }
+
+  if (config.payloadInfo.length === 0) {
+    issues.push({
+      path: `${path}.payloadInfo`,
+      message: "payloadInfo must contain at least one payload",
+      severity: "warning",
+    });
+  }
+
+  return issues;
+}

package/src/validate/validate-template.ts

@@ -0,0 +1,101 @@
+import type { Issue } from "../types/errors.js";
+import type {
+  Mapping2dTemplate,
+  Mapping3dTemplate,
+  MappingStripTemplate,
+  Template,
+  WaypointTemplate,
+} from "../types/template.js";
+
+export function validateTemplate(template: Template): Issue[] {
+  const folder = template.Folder;
+  const issues: Issue[] = [];
+  const path = "Folder";
+
+  if (folder.templateId < 0 || folder.templateId > 65535) {
+    issues.push({
+      path: `${path}.templateId`,
+      message: `templateId must be in [0,65535], got ${folder.templateId}`,
+      severity: "error",
+    });
+  }
+
+  if (folder.autoFlightSpeed < 1 || folder.autoFlightSpeed > 15) {
+    issues.push({
+      path: `${path}.autoFlightSpeed`,
+      message: `autoFlightSpeed must be in [1,15] m/s, got ${folder.autoFlightSpeed}`,
+      severity: "error",
+    });
+  }
+
+  switch (folder.templateType) {
+    case "waypoint":
+      issues.push(...validateWaypointFolder(template as WaypointTemplate, path));
+      break;
+    case "mapping2d":
+      issues.push(...validateMapping2dFolder(template as Mapping2dTemplate, path));
+      break;
+    case "mapping3d":
+      issues.push(...validateMapping3dFolder(template as Mapping3dTemplate, path));
+      break;
+    case "mappingStrip":
+      issues.push(...validateMappingStripFolder(template as MappingStripTemplate, path));
+      break;
+  }
+
+  return issues;
+}
+
+function validateWaypointFolder(t: WaypointTemplate, path: string): Issue[] {
+  const issues: Issue[] = [];
+  if (t.Folder.Placemark.length === 0) {
+    issues.push({
+      path: `${path}.Placemark`,
+      message: "waypoint template must have at least one Placemark",
+      severity: "error",
+    });
+  }
+  return issues;
+}
+
+function validateMapping2dFolder(t: Mapping2dTemplate, path: string): Issue[] {
+  return validatePolygonRing(
+    t.Folder.Placemark.Polygon.outerBoundaryIs.LinearRing.coordinates,
+    `${path}.Placemark.Polygon`,
+  );
+}
+
+function validateMapping3dFolder(t: Mapping3dTemplate, path: string): Issue[] {
+  return validatePolygonRing(
+    t.Folder.Placemark.Polygon.outerBoundaryIs.LinearRing.coordinates,
+    `${path}.Placemark.Polygon`,
+  );
+}
+
+function validateMappingStripFolder(t: MappingStripTemplate, path: string): Issue[] {
+  const tuples = t.Folder.Placemark.LineString.coordinates.trim().split(/\s+/);
+  if (tuples.length < 2) {
+    return [
+      {
+        path: `${path}.Placemark.LineString`,
+        message: `LineString must have at least 2 vertices, got ${tuples.length}`,
+        severity: "error",
+      },
+    ];
+  }
+  return [];
+}
+
+function validatePolygonRing(coords: string, path: string): Issue[] {
+  const tuples = coords.trim().split(/\s+/);
+  if (tuples.length < 3) {
+    return [
+      {
+        path,
+        message: `Polygon boundary must have at least 3 vertices, got ${tuples.length}`,
+        severity: "error",
+      },
+    ];
+  }
+  return [];
+}

package/src/validate/validate-waylines.ts

@@ -0,0 +1,59 @@
+import type { Issue } from "../types/errors.js";
+import type { Waylines, WaylinesFolder } from "../types/waylines.js";
+
+export function validateWaylines(waylines: Waylines): Issue[] {
+  const issues: Issue[] = [];
+
+  if (waylines.Folder.length === 0) {
+    issues.push({
+      path: "Folder",
+      message: "Waylines must contain at least one Folder",
+      severity: "error",
+    });
+  }
+
+  waylines.Folder.forEach((folder, i) => {
+    issues.push(...validateFolder(folder, `Folder[${i}]`));
+  });
+
+  return issues;
+}
+
+function validateFolder(folder: WaylinesFolder, path: string): Issue[] {
+  const issues: Issue[] = [];
+
+  if (folder.autoFlightSpeed < 1 || folder.autoFlightSpeed > 15) {
+    issues.push({
+      path: `${path}.autoFlightSpeed`,
+      message: `autoFlightSpeed must be in [1,15] m/s, got ${folder.autoFlightSpeed}`,
+      severity: "error",
+    });
+  }
+
+  if (folder.Placemark.length === 0) {
+    issues.push({
+      path: `${path}.Placemark`,
+      message: "Folder must contain at least one Placemark",
+      severity: "error",
+    });
+  }
+
+  folder.Placemark.forEach((p, i) => {
+    if (p.index !== i) {
+      issues.push({
+        path: `${path}.Placemark[${i}].index`,
+        message: `Placemark.index must equal its array position (expected ${i}, got ${p.index})`,
+        severity: "error",
+      });
+    }
+    if (p.waypointSpeed < 1 || p.waypointSpeed > 15) {
+      issues.push({
+        path: `${path}.Placemark[${i}].waypointSpeed`,
+        message: `waypointSpeed must be in [1,15] m/s, got ${p.waypointSpeed}`,
+        severity: "error",
+      });
+    }
+  });
+
+  return issues;
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src"]
+}

package/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  pack: {
+    entry: ["src/index.ts"],
+    format: "esm",
+    dts: true,
+  },
+});