@lumikmz/kmz 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,789 @@
+//#region src/types/branded.d.ts
+type Brand<T, B> = T & {
+  readonly __brand: B;
+};
+type Meters = Brand<number, "Meters">;
+type MetersPerSecond = Brand<number, "MetersPerSecond">;
+type Degrees = Brand<number, "Degrees">;
+declare const meters: (n: number) => Meters;
+declare const metersPerSecond: (n: number) => MetersPerSecond;
+declare const degrees: (n: number) => Degrees;
+interface LngLat {
+  readonly lng: number;
+  readonly lat: number;
+}
+interface LngLatHeight {
+  readonly lng: number;
+  readonly lat: number;
+  readonly height: Meters;
+}
+//#endregion
+//#region src/types/errors.d.ts
+declare class KmzError extends Error {
+  constructor(message: string);
+}
+declare class PlannerError extends KmzError {
+  constructor(message: string);
+}
+interface Issue {
+  path: string;
+  message: string;
+  severity: "error" | "warning";
+}
+//#endregion
+//#region src/types/enums.d.ts
+type FlyToWaylineMode = "safely" | "pointToPoint";
+type FinishAction = "goHome" | "noAction" | "autoLand" | "gotoFirstWaypoint";
+type ExitOnRCLost = "goContinue" | "executeLostAction";
+type ExecuteRCLostAction = "goBack" | "landing" | "hover";
+type TemplateType = "waypoint" | "mapping2d" | "mapping3d" | "mappingStrip";
+type CoordinateMode = "WGS84";
+/** Used in template.kml `waylineCoordinateSysParam.heightMode`. */
+type TemplateHeightMode = "EGM96" | "relativeToStartPoint" | "aboveGroundLevel" | "realTimeFollowSurface";
+/** Used in waylines.wpml `Folder.executeHeightMode`. */
+type ExecuteHeightMode = "WGS84" | "relativeToStartPoint" | "realTimeFollowSurface";
+type PositioningType = "GPS" | "RTKBaseStation" | "QianXun" | "Custom";
+type WaypointTurnMode = "coordinateTurn" | "toPointAndStopWithDiscontinuityCurvature" | "toPointAndStopWithContinuityCurvature" | "toPointAndPassWithContinuityCurvature";
+type WaypointHeadingMode = "followWayline" | "manually" | "fixed" | "smoothTransition" | "towardPOI";
+/** Spec typo preserved: `followBadArc` (intended "shortest path / smaller arc"). */
+type WaypointHeadingPathMode = "clockwise" | "counterClockwise" | "followBadArc";
+/** Template waypoint folder allows manual + per-point; mapping templates allow manual + fixed. */
+type GimbalPitchMode = "manual" | "usePointSetting" | "fixed";
+type ShootType = "time" | "distance";
+type MappingHeadingMode = "fixed" | "followWayline";
+/** Spec typo preserved: `visable`. */
+type LensType = "wide" | "zoom" | "ir" | "narrow_band" | "visable";
+type FocusMode = "firstPoint" | "custom";
+type MeteringMode = "average" | "spot";
+type LidarReturnMode = "singleReturnStrongest" | "dualReturn" | "tripleReturn";
+type LidarScanningMode = "repetitive" | "nonRepetitive";
+type ActionGroupMode = "sequence";
+type ActionTriggerType = "reachPoint" | "betweenAdjacentPoints" | "multipleTiming" | "multipleDistance";
+type ActionActuatorFunc = "takePhoto" | "startRecord" | "stopRecord" | "focus" | "zoom" | "customDirName" | "gimbalRotate" | "rotateYaw" | "hover" | "gimbalEvenlyRotate" | "accurateShoot" | "orientedShoot" | "panoShot" | "recordPointCloud" | "megaphone" | "searchlight";
+type GimbalHeadingYawBase = "north";
+type GimbalRotateMode = "absoluteAngle";
+type AircraftPathMode = "clockwise" | "counterClockwise";
+type RecordPointCloudOperate = "startRecord" | "pauseRecord" | "resumeRecord" | "stopRecord";
+type PanoShotSubMode = "panoShot_360";
+type OrientedPhotoMode = "normalPhoto" | "lowLightSmartShooting";
+//#endregion
+//#region src/types/drone-payload.d.ts
+interface DroneInfo {
+  droneEnumValue: number;
+  droneSubEnumValue?: number;
+}
+interface PayloadInfo {
+  payloadEnumValue: number;
+  payloadPositionIndex: number;
+}
+/** Aircraft `{ droneEnumValue, droneSubEnumValue }` tuples. */
+declare const DroneEnum: {
+  readonly M400: {
+    readonly droneEnumValue: 103;
+    readonly droneSubEnumValue: 0;
+  };
+  readonly M350RTK: {
+    readonly droneEnumValue: 89;
+    readonly droneSubEnumValue: 0;
+  };
+  readonly M300RTK: {
+    readonly droneEnumValue: 60;
+    readonly droneSubEnumValue: 0;
+  };
+  readonly M30: {
+    readonly droneEnumValue: 67;
+    readonly droneSubEnumValue: 0;
+  };
+  readonly M30T: {
+    readonly droneEnumValue: 67;
+    readonly droneSubEnumValue: 1;
+  };
+  readonly M3E: {
+    readonly droneEnumValue: 77;
+    readonly droneSubEnumValue: 0;
+  };
+  readonly M3T: {
+    readonly droneEnumValue: 77;
+    readonly droneSubEnumValue: 1;
+  };
+  readonly M3TA: {
+    readonly droneEnumValue: 77;
+    readonly droneSubEnumValue: 3;
+  };
+  readonly M3D: {
+    readonly droneEnumValue: 91;
+    readonly droneSubEnumValue: 0;
+  };
+  readonly M3TD: {
+    readonly droneEnumValue: 91;
+    readonly droneSubEnumValue: 1;
+  };
+  readonly M4D: {
+    readonly droneEnumValue: 100;
+    readonly droneSubEnumValue: 0;
+  };
+  readonly M4TD: {
+    readonly droneEnumValue: 100;
+    readonly droneSubEnumValue: 1;
+  };
+  readonly M4E: {
+    readonly droneEnumValue: 99;
+    readonly droneSubEnumValue: 0;
+  };
+  readonly M4T: {
+    readonly droneEnumValue: 99;
+    readonly droneSubEnumValue: 1;
+  };
+};
+/** Payload `{ payloadEnumValue, payloadPositionIndex }` tuples for common cameras. */
+declare const PayloadEnum: {
+  readonly M30Camera: {
+    readonly payloadEnumValue: 52;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M30TCamera: {
+    readonly payloadEnumValue: 53;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M3ECamera: {
+    readonly payloadEnumValue: 66;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M3TCamera: {
+    readonly payloadEnumValue: 67;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M3TACamera: {
+    readonly payloadEnumValue: 129;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M3DCamera: {
+    readonly payloadEnumValue: 80;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M3TDCamera: {
+    readonly payloadEnumValue: 81;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M4DCamera: {
+    readonly payloadEnumValue: 98;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M4TDCamera: {
+    readonly payloadEnumValue: 99;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M4ECamera: {
+    readonly payloadEnumValue: 88;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly M4TCamera: {
+    readonly payloadEnumValue: 89;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly ZenmuseZ30: {
+    readonly payloadEnumValue: 20;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly ZenmuseXT2: {
+    readonly payloadEnumValue: 26;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly ZenmuseXTS: {
+    readonly payloadEnumValue: 41;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly ZenmuseH20: {
+    readonly payloadEnumValue: 42;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly ZenmuseH20T: {
+    readonly payloadEnumValue: 43;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly ZenmuseH20N: {
+    readonly payloadEnumValue: 61;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly ZenmuseH30: {
+    readonly payloadEnumValue: 82;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly ZenmuseH30T: {
+    readonly payloadEnumValue: 83;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly FPVMatriceSeries: {
+    readonly payloadEnumValue: 39;
+    readonly payloadPositionIndex: 7;
+  };
+  readonly AuxiliaryM3xM4x: {
+    readonly payloadEnumValue: 176;
+    readonly payloadPositionIndex: 0;
+  };
+  readonly DockCamera: {
+    readonly payloadEnumValue: 165;
+    readonly payloadPositionIndex: 7;
+  };
+};
+//#endregion
+//#region src/types/mission-config.d.ts
+/**
+ * `wpml:missionConfig` — shared between template.kml and waylines.wpml.
+ * See `docs/kmz/common-element.html` §missionConfig.
+ */
+interface MissionConfig {
+  flyToWaylineMode: FlyToWaylineMode;
+  finishAction: FinishAction;
+  exitOnRCLost: ExitOnRCLost;
+  /** Required iff `exitOnRCLost === "executeLostAction"`. */
+  executeRCLostAction?: ExecuteRCLostAction;
+  takeOffSecurityHeight: Meters;
+  /** lat/lng with WGS84 ellipsoid height. Optional; only used for planning. */
+  takeOffRefPoint?: LngLatHeight;
+  /** AGL altitude of `takeOffRefPoint`. Paired with the ellipsoid height inside `takeOffRefPoint.height`. */
+  takeOffRefPointAGLHeight?: Meters;
+  globalTransitionalSpeed: MetersPerSecond;
+  globalRTHHeight: Meters;
+  droneInfo: DroneInfo;
+  payloadInfo: PayloadInfo[];
+  /** Only M3D/M3TD, M4D/M4TD, M4E/M4T. */
+  autoRerouteInfo?: AutoRerouteInfo;
+}
+interface AutoRerouteInfo {
+  missionAutoRerouteMode: boolean;
+  transitionalAutoRerouteMode: boolean;
+}
+/**
+ * `wpml:payloadParam` — per-payload imaging settings.
+ * Lives under template `Folder`.
+ */
+interface PayloadParam {
+  payloadPositionIndex: number;
+  focusMode?: FocusMode;
+  meteringMode?: MeteringMode;
+  dewarpingEnable?: boolean;
+  returnMode?: LidarReturnMode;
+  samplingRate?: 60000 | 80000 | 120000 | 160000 | 180000 | 240000;
+  scanningMode?: LidarScanningMode;
+  modelColoringEnable?: boolean;
+  /** Comma-joined `LensType` tokens, e.g. `["wide","ir"]`. */
+  imageFormat: LensType[];
+}
+//#endregion
+//#region src/types/waypoint-params.d.ts
+/**
+ * `wpml:waypointHeadingParam` & `wpml:globalWaypointHeadingParam`.
+ * See `docs/kmz/common-element.html` §waypointHeadingParam.
+ */
+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.
+ */
+interface WaypointTurnParam {
+  waypointTurnMode: WaypointTurnMode;
+  /**
+   * Required iff `waypointTurnMode === "coordinateTurn"`
+   * OR (`waypointTurnMode === "toPointAndPassWithContinuityCurvature"` AND useStraightLine = 1).
+   */
+  waypointTurnDampingDist?: Meters;
+}
+/**
+ * `wpml:waylineCoordinateSysParam`.
+ * Mapping templates require globalShootHeight + surfaceFollowModeEnable.
+ */
+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).
+ */
+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.
+ */
+interface Overlap {
+  orthoLidarOverlapH?: number;
+  orthoLidarOverlapW?: number;
+  orthoCameraOverlapH?: number;
+  orthoCameraOverlapW?: number;
+  inclinedLidarOverlapH?: number;
+  inclinedLidarOverlapW?: number;
+  inclinedCameraOverlapH?: number;
+  inclinedCameraOverlapW?: number;
+}
+//#endregion
+//#region src/types/action.d.ts
+/**
+ * `wpml:actionGroup` — see `docs/kmz/common-element.html` §actionGroup.
+ *
+ * - `actionGroupId` is unique within the entire KMZ (monotonically from 0).
+ * - `actionId` is scoped within its group.
+ */
+interface ActionGroup {
+  actionGroupId: number;
+  actionGroupStartIndex: number;
+  actionGroupEndIndex: number;
+  actionGroupMode: ActionGroupMode;
+  actionTrigger: ActionTrigger;
+  action: Action[];
+}
+interface ActionTrigger {
+  actionTriggerType: ActionTriggerType;
+  /** Seconds for `multipleTiming`, meters for `multipleDistance`. */
+  actionTriggerParam?: number;
+}
+/** Discriminated by `actionActuatorFunc`. */
+type Action = TakePhotoAction | StartRecordAction | StopRecordAction | FocusAction | ZoomAction | CustomDirNameAction | GimbalRotateAction | RotateYawAction | HoverAction | GimbalEvenlyRotateAction | AccurateShootAction | OrientedShootAction | PanoShotAction | RecordPointCloudAction | MegaphoneAction | SearchlightAction;
+interface ActionBase<F extends string, P> {
+  actionId: number;
+  actionActuatorFunc: F;
+  actionActuatorFuncParam: P;
+}
+interface TakePhotoParam {
+  payloadPositionIndex: number;
+  fileSuffix?: string;
+  payloadLensIndex?: LensType[];
+  useGlobalPayloadLensIndex: boolean;
+}
+type TakePhotoAction = ActionBase<"takePhoto", TakePhotoParam>;
+interface StartRecordParam {
+  payloadPositionIndex: number;
+  fileSuffix?: string;
+  payloadLensIndex?: LensType[];
+  useGlobalPayloadLensIndex: boolean;
+}
+type StartRecordAction = ActionBase<"startRecord", StartRecordParam>;
+interface StopRecordParam {
+  payloadPositionIndex: number;
+  payloadLensIndex?: LensType[];
+}
+type StopRecordAction = ActionBase<"stopRecord", StopRecordParam>;
+interface FocusParam {
+  payloadPositionIndex: number;
+  isPointFocus: boolean;
+  focusX: number;
+  focusY: number;
+  /** Required iff `isPointFocus === false`. */
+  focusRegionWidth?: number;
+  /** Required iff `isPointFocus === false`. */
+  focusRegionHeight?: number;
+  /** Required on M3E/M3T/M3M, M3D/M3TD, M4D/M4TD, M4E/M4T. */
+  isInfiniteFocus?: boolean;
+}
+type FocusAction = ActionBase<"focus", FocusParam>;
+interface ZoomParam {
+  payloadPositionIndex: number;
+  /** mm, > 0. */
+  focalLength: number;
+}
+type ZoomAction = ActionBase<"zoom", ZoomParam>;
+interface CustomDirNameParam {
+  payloadPositionIndex: number;
+  directoryName: string;
+}
+type CustomDirNameAction = ActionBase<"customDirName", CustomDirNameParam>;
+interface GimbalRotateParam {
+  payloadPositionIndex: number;
+  gimbalHeadingYawBase: GimbalHeadingYawBase;
+  gimbalRotateMode: GimbalRotateMode;
+  gimbalPitchRotateEnable: boolean;
+  gimbalPitchRotateAngle: Degrees;
+  gimbalRollRotateEnable: boolean;
+  gimbalRollRotateAngle: Degrees;
+  gimbalYawRotateEnable: boolean;
+  gimbalYawRotateAngle: Degrees;
+  gimbalRotateTimeEnable: boolean;
+  /** seconds */
+  gimbalRotateTime: number;
+}
+type GimbalRotateAction = ActionBase<"gimbalRotate", GimbalRotateParam>;
+interface RotateYawParam {
+  /** `[-180, 180]`, 0=N, 90=E, -90=W, ±180=S. */
+  aircraftHeading: Degrees;
+  /** Required on M300/M350. */
+  aircraftPathMode?: AircraftPathMode;
+}
+type RotateYawAction = ActionBase<"rotateYaw", RotateYawParam>;
+interface HoverParam {
+  /** seconds, > 0. */
+  hoverTime: number;
+}
+type HoverAction = ActionBase<"hover", HoverParam>;
+interface GimbalEvenlyRotateParam {
+  payloadPositionIndex: number;
+  gimbalPitchRotateAngle: Degrees;
+}
+/** Must be paired with `actionTriggerType === "betweenAdjacentPoints"`. */
+type GimbalEvenlyRotateAction = ActionBase<"gimbalEvenlyRotate", GimbalEvenlyRotateParam>;
+/** Deprecated for M30/M30T after firmware V06.01.10.02. Prefer `orientedShoot`. */
+interface AccurateShootParam {
+  gimbalPitchRotateAngle: Degrees;
+  gimbalYawRotateAngle: Degrees;
+  focusX: number;
+  focusY: number;
+  focusRegionWidth: number;
+  focusRegionHeight: number;
+  focalLength: number;
+  aircraftHeading: Degrees;
+  accurateFrameValid: boolean;
+  payloadPositionIndex: number;
+  payloadLensIndex: LensType[];
+  useGlobalPayloadLensIndex: boolean;
+  targetAngle: Degrees;
+  imageWidth: number;
+  imageHeight: number;
+  AFPos: number;
+  gimbalPort: number;
+  accurateCameraType: number;
+  accurateFilePath: string;
+  accurateFileMD5: string;
+  accurateFileSize: number;
+  accurateFileSuffix: string;
+  accurateCameraApertue?: number;
+  accurateCameraLuminance?: number;
+  accurateCameraShutterTime?: number;
+  accurateCameraISO?: number;
+}
+type AccurateShootAction = ActionBase<"accurateShoot", AccurateShootParam>;
+interface OrientedShootParam {
+  gimbalPitchRotateAngle: Degrees;
+  gimbalYawRotateAngle: Degrees;
+  focusX: number;
+  focusY: number;
+  focusRegionWidth: number;
+  focusRegionHeight: number;
+  focalLength: number;
+  aircraftHeading: Degrees;
+  accurateFrameValid: boolean;
+  payloadPositionIndex: number;
+  payloadLensIndex: LensType[];
+  useGlobalPayloadLensIndex: boolean;
+  targetAngle: Degrees;
+  actionUUID: string;
+  imageWidth: number;
+  imageHeight: number;
+  AFPos: number;
+  gimbalPort: number;
+  orientedCameraType: number;
+  orientedFilePath: string;
+  orientedFileMD5: string;
+  orientedFileSize: number;
+  orientedFileSuffix: string;
+  orientedCameraApertue: number;
+  orientedCameraLuminance: number;
+  orientedCameraShutterTime: number;
+  orientedCameraISO: number;
+  orientedPhotoMode: OrientedPhotoMode;
+}
+type OrientedShootAction = ActionBase<"orientedShoot", OrientedShootParam>;
+interface PanoShotParam {
+  payloadPositionIndex?: number;
+  payloadLensIndex?: LensType[];
+  useGlobalPayloadLensIndex?: boolean;
+  panoShotSubMode: PanoShotSubMode;
+}
+type PanoShotAction = ActionBase<"panoShot", PanoShotParam>;
+interface RecordPointCloudParam {
+  payloadPositionIndex: number;
+  recordPointCloudOperate: RecordPointCloudOperate;
+}
+type RecordPointCloudAction = ActionBase<"recordPointCloud", RecordPointCloudParam>;
+/** M4D/M4TD only. */
+interface MegaphoneParam {
+  payloadPositionIndex: number;
+  actionUUID: string;
+  /** 0 = start, 1 = stop. */
+  megaphoneOperateType: 0 | 1;
+  /** 0–100. */
+  megaphoneOperateVolume: number;
+  megaphoneOperateLoop: boolean;
+  /** Path inside KMZ, e.g. `/wpmz/res/audio/<hash>.opus`. */
+  megaphoneOperateFilePath: string;
+  megaphoneFileName: string;
+  megaphoneFileOriginalName: string;
+  megaphoneFileMd5: string;
+  /** 1=8000, 2=16000, 3=24000, 4=32000, 5=48000, 6=64000 (only 4 supported today). */
+  megaphoneFileBitrate: 1 | 2 | 3 | 4 | 5 | 6;
+}
+type MegaphoneAction = ActionBase<"megaphone", MegaphoneParam>;
+/** M4D/M4TD only. */
+interface SearchlightParam {
+  payloadPositionIndex: number;
+  actionUUID?: string;
+  /** 0 = off, 1 = illuminate, 2 = flash. */
+  searchlightOperateType: 0 | 1 | 2;
+  /** 0–100. */
+  searchlightBrightness: number;
+}
+type SearchlightAction = ActionBase<"searchlight", SearchlightParam>;
+//#endregion
+//#region src/types/placemark.d.ts
+/**
+ * `Placemark` inside a `waypoint`-type Folder of template.kml.
+ *
+ * Note coordinate order: `Point.coordinates` is `lon,lat` per KML (no altitude).
+ */
+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.
+ */
+interface TemplatePolygonPlacemark {
+  Polygon: {
+    outerBoundaryIs: {
+      LinearRing: {
+        /** Space-separated `lon,lat,alt` triples. */coordinates: string;
+      };
+    };
+  };
+}
+/** Placemark for `mappingStrip` Folder — uses a LineString. */
+interface TemplateLineStringPlacemark {
+  LineString: {
+    /** Space-separated `lon,lat,alt` triples. Alt consumed only when `stripUseTemplateAltitude === true`. */coordinates: string;
+  };
+}
+/**
+ * `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.
+ */
+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[];
+}
+//#endregion
+//#region src/types/template.d.ts
+/**
+ * `template.kml` document. Mirrors `<kml><Document>` structure.
+ * See `docs/kmz/template-kml.html`.
+ */
+type Template = WaypointTemplate | Mapping2dTemplate | Mapping3dTemplate | MappingStripTemplate;
+interface TemplateDocumentBase {
+  /** Unix milliseconds. */
+  author?: string;
+  createTime?: number;
+  updateTime?: number;
+  missionConfig: MissionConfig;
+}
+interface WaypointTemplate extends TemplateDocumentBase {
+  Folder: WaypointFolder;
+}
+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[];
+}
+interface Mapping2dTemplate extends TemplateDocumentBase {
+  Folder: Mapping2dFolder;
+}
+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;
+}
+interface Mapping3dTemplate extends TemplateDocumentBase {
+  Folder: Mapping3dFolder;
+}
+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;
+}
+interface MappingStripTemplate extends TemplateDocumentBase {
+  Folder: MappingStripFolder;
+}
+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;
+}
+//#endregion
+//#region src/types/waylines.d.ts
+/**
+ * `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).
+ */
+interface Waylines {
+  missionConfig: MissionConfig;
+  Folder: WaylinesFolder[];
+}
+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[];
+}
+//#endregion
+//#region src/plan/index.d.ts
+/**
+ * Compile a high-level `Template` into executable `Waylines`.
+ * Dispatch is by `template.Folder.templateType` per the DJI WPML spec.
+ */
+declare function plan(template: Template): Waylines;
+//#endregion
+//#region src/validate/index.d.ts
+/**
+ * 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.
+ */
+declare function validate(doc: Template | Waylines): Issue[];
+//#endregion
+export { AccurateShootAction, AccurateShootParam, Action, ActionActuatorFunc, ActionGroup, ActionGroupMode, ActionTrigger, ActionTriggerType, AircraftPathMode, AutoRerouteInfo, CoordinateMode, CustomDirNameAction, CustomDirNameParam, Degrees, DroneEnum, DroneInfo, type ExecuteHeightMode, ExecuteRCLostAction, ExitOnRCLost, FinishAction, FlyToWaylineMode, FocusAction, FocusMode, FocusParam, GimbalEvenlyRotateAction, GimbalEvenlyRotateParam, GimbalHeadingYawBase, GimbalPitchMode, GimbalRotateAction, GimbalRotateMode, GimbalRotateParam, HoverAction, HoverParam, type Issue, KmzError, LensType, LidarReturnMode, LidarScanningMode, LngLat, LngLatHeight, Mapping2dFolder, Mapping2dTemplate, Mapping3dFolder, Mapping3dTemplate, MappingHeadingMode, MappingHeadingParam, MappingStripFolder, MappingStripTemplate, MegaphoneAction, MegaphoneParam, MeteringMode, Meters, MetersPerSecond, MissionConfig, OrientedPhotoMode, OrientedShootAction, OrientedShootParam, Overlap, PanoShotAction, PanoShotParam, PanoShotSubMode, PayloadEnum, PayloadInfo, PayloadParam, PlannerError, PositioningType, RecordPointCloudAction, RecordPointCloudOperate, RecordPointCloudParam, RotateYawAction, RotateYawParam, SearchlightAction, SearchlightParam, ShootType, StartRecordAction, StartRecordParam, StopRecordAction, StopRecordParam, TakePhotoAction, TakePhotoParam, Template, TemplateHeightMode, TemplateLineStringPlacemark, TemplatePolygonPlacemark, TemplateType, TemplateWaypointPlacemark, WaylineCoordinateSysParam, Waylines, WaylinesFolder, WaylinesPlacemark, WaypointFolder, WaypointHeadingMode, WaypointHeadingParam, WaypointHeadingPathMode, WaypointTemplate, WaypointTurnMode, WaypointTurnParam, ZoomAction, ZoomParam, degrees, meters, metersPerSecond, plan, validate };