@lumikmz/kmz 0.2.0

package/dist/index.mjs

@@ -0,0 +1,779 @@
+//#region src/types/branded.ts
+const meters = (n) => n;
+const metersPerSecond = (n) => n;
+const degrees = (n) => n;
+//#endregion
+//#region src/types/errors.ts
+var KmzError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "KmzError";
+	}
+};
+var PlannerError = class extends KmzError {
+	constructor(message) {
+		super(message);
+		this.name = "PlannerError";
+	}
+};
+//#endregion
+//#region src/types/drone-payload.ts
+/** Aircraft `{ droneEnumValue, droneSubEnumValue }` tuples. */
+const DroneEnum = {
+	M400: {
+		droneEnumValue: 103,
+		droneSubEnumValue: 0
+	},
+	M350RTK: {
+		droneEnumValue: 89,
+		droneSubEnumValue: 0
+	},
+	M300RTK: {
+		droneEnumValue: 60,
+		droneSubEnumValue: 0
+	},
+	M30: {
+		droneEnumValue: 67,
+		droneSubEnumValue: 0
+	},
+	M30T: {
+		droneEnumValue: 67,
+		droneSubEnumValue: 1
+	},
+	M3E: {
+		droneEnumValue: 77,
+		droneSubEnumValue: 0
+	},
+	M3T: {
+		droneEnumValue: 77,
+		droneSubEnumValue: 1
+	},
+	M3TA: {
+		droneEnumValue: 77,
+		droneSubEnumValue: 3
+	},
+	M3D: {
+		droneEnumValue: 91,
+		droneSubEnumValue: 0
+	},
+	M3TD: {
+		droneEnumValue: 91,
+		droneSubEnumValue: 1
+	},
+	M4D: {
+		droneEnumValue: 100,
+		droneSubEnumValue: 0
+	},
+	M4TD: {
+		droneEnumValue: 100,
+		droneSubEnumValue: 1
+	},
+	M4E: {
+		droneEnumValue: 99,
+		droneSubEnumValue: 0
+	},
+	M4T: {
+		droneEnumValue: 99,
+		droneSubEnumValue: 1
+	}
+};
+/** Payload `{ payloadEnumValue, payloadPositionIndex }` tuples for common cameras. */
+const PayloadEnum = {
+	M30Camera: {
+		payloadEnumValue: 52,
+		payloadPositionIndex: 0
+	},
+	M30TCamera: {
+		payloadEnumValue: 53,
+		payloadPositionIndex: 0
+	},
+	M3ECamera: {
+		payloadEnumValue: 66,
+		payloadPositionIndex: 0
+	},
+	M3TCamera: {
+		payloadEnumValue: 67,
+		payloadPositionIndex: 0
+	},
+	M3TACamera: {
+		payloadEnumValue: 129,
+		payloadPositionIndex: 0
+	},
+	M3DCamera: {
+		payloadEnumValue: 80,
+		payloadPositionIndex: 0
+	},
+	M3TDCamera: {
+		payloadEnumValue: 81,
+		payloadPositionIndex: 0
+	},
+	M4DCamera: {
+		payloadEnumValue: 98,
+		payloadPositionIndex: 0
+	},
+	M4TDCamera: {
+		payloadEnumValue: 99,
+		payloadPositionIndex: 0
+	},
+	M4ECamera: {
+		payloadEnumValue: 88,
+		payloadPositionIndex: 0
+	},
+	M4TCamera: {
+		payloadEnumValue: 89,
+		payloadPositionIndex: 0
+	},
+	ZenmuseZ30: {
+		payloadEnumValue: 20,
+		payloadPositionIndex: 0
+	},
+	ZenmuseXT2: {
+		payloadEnumValue: 26,
+		payloadPositionIndex: 0
+	},
+	ZenmuseXTS: {
+		payloadEnumValue: 41,
+		payloadPositionIndex: 0
+	},
+	ZenmuseH20: {
+		payloadEnumValue: 42,
+		payloadPositionIndex: 0
+	},
+	ZenmuseH20T: {
+		payloadEnumValue: 43,
+		payloadPositionIndex: 0
+	},
+	ZenmuseH20N: {
+		payloadEnumValue: 61,
+		payloadPositionIndex: 0
+	},
+	ZenmuseH30: {
+		payloadEnumValue: 82,
+		payloadPositionIndex: 0
+	},
+	ZenmuseH30T: {
+		payloadEnumValue: 83,
+		payloadPositionIndex: 0
+	},
+	FPVMatriceSeries: {
+		payloadEnumValue: 39,
+		payloadPositionIndex: 7
+	},
+	AuxiliaryM3xM4x: {
+		payloadEnumValue: 176,
+		payloadPositionIndex: 0
+	},
+	DockCamera: {
+		payloadEnumValue: 165,
+		payloadPositionIndex: 7
+	}
+};
+//#endregion
+//#region src/plan/geometry.ts
+const EARTH_RADIUS = 6371e3;
+const DEG2RAD = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+/** Project lng/lat to local ENU meters around `origin`. */
+function lngLatToEnu(point, origin) {
+	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`. */
+function enuToLngLat([x, y], origin) {
+	const avgLat = origin.lat * DEG2RAD;
+	return {
+		lng: origin.lng + x / (EARTH_RADIUS * Math.cos(avgLat)) * RAD2DEG,
+		lat: origin.lat + y / EARTH_RADIUS * RAD2DEG
+	};
+}
+function centroid(points) {
+	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.
+*/
+function bearingDeg(from, to) {
+	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, polygon) {
+	const intersections = [];
+	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 = [];
+	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. */
+function scanWaypoints(polygon, lineSpacing) {
+	let minY = Infinity;
+	let maxY = -Infinity;
+	for (const [, y] of polygon) {
+		if (y < minY) minY = y;
+		if (y > maxY) maxY = y;
+	}
+	const waypoints = [];
+	let leftToRight = true;
+	for (let y = minY; y <= maxY + lineSpacing * .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).
+*/
+function parseCoordinatesString(s) {
+	return s.trim().split(/\s+/).map((tuple) => {
+		const [lng, lat] = tuple.split(",").map(Number);
+		return {
+			lng,
+			lat
+		};
+	});
+}
+//#endregion
+//#region src/plan/plan-mapping2d.ts
+/** Default HFOV (degrees) used to estimate ground footprint when payload-specific FOV unknown. */
+const DEFAULT_HFOV_DEG$1 = 84;
+function planMapping2d(template) {
+	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$1 / 2 * (Math.PI / 180);
+	const enuWps = scanWaypoints(enuPolygon, 2 * folder.height * Math.tan(hfovRad) * (1 - (folder.overlap.orthoCameraOverlapW ?? 70) / 100));
+	const lngLatWps = enuWps.map((p) => enuToLngLat(p, origin));
+	let actionGroupId = 0;
+	const placemarks = lngLatWps.map((coord, index) => {
+		const isLast = index === lngLatWps.length - 1;
+		const headingAngle = isLast ? 0 : bearingDeg(enuWps[index], enuWps[index + 1]);
+		const 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 = {
+		templateId: folder.templateId,
+		waylineId: 0,
+		executeHeightMode: heightModeToExecuteMode$3(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$3(folder) {
+	switch (folder.waylineCoordinateSysParam.heightMode) {
+		case "EGM96": return "WGS84";
+		case "relativeToStartPoint": return "relativeToStartPoint";
+		case "aboveGroundLevel":
+		case "realTimeFollowSurface": return "realTimeFollowSurface";
+	}
+}
+//#endregion
+//#region src/plan/plan-mapping3d.ts
+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).
+*/
+function planMapping3d(template) {
+	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 enuWps = scanWaypoints(enuPolygon, 2 * folder.height * Math.tan(hfovRad) * (1 - (folder.overlap.orthoCameraOverlapW ?? 70) / 100));
+	const Folder = [
+		{
+			headingAngle: 0,
+			gimbalPitch: -90,
+			minShootInterval: 2
+		},
+		{
+			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
+		}
+	].map((pass, i) => buildObliquePass(folder, i, origin, enuWps, pass.headingAngle, pass.gimbalPitch, pass.minShootInterval));
+	return {
+		missionConfig: template.missionConfig,
+		Folder
+	};
+}
+function buildObliquePass(folder, waylineId, origin, enuWps, headingAngle, gimbalPitch, minShootInterval) {
+	const lastIndex = enuWps.length - 1;
+	const placemarks = enuWps.map((enu, index) => {
+		const placemark = {
+			Point: { coordinates: enuToLngLat(enu, origin) },
+			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$2(folder.waylineCoordinateSysParam.heightMode),
+		autoFlightSpeed: folder.autoFlightSpeed,
+		startActionGroup: startGimbalRotateGroup(gimbalPitch),
+		Placemark: placemarks
+	};
+}
+function waypointActionGroups(index, lastIndex, gimbalPitch, minShootInterval) {
+	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) {
+	return {
+		actionGroupId: 65535,
+		actionGroupStartIndex: 0,
+		actionGroupEndIndex: 0,
+		actionGroupMode: "sequence",
+		actionTrigger: { actionTriggerType: "reachPoint" },
+		action: [gimbalRotate(0, gimbalPitch)]
+	};
+}
+function gimbalRotate(actionId, pitch) {
+	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) {
+	return {
+		actionId,
+		actionActuatorFunc: "takePhoto",
+		actionActuatorFuncParam: {
+			payloadPositionIndex: 0,
+			payloadLensIndex: ["wide"],
+			useGlobalPayloadLensIndex: false
+		}
+	};
+}
+function heightModeToExecuteMode$2(mode) {
+	switch (mode) {
+		case "EGM96": return "WGS84";
+		case "relativeToStartPoint": return "relativeToStartPoint";
+		case "aboveGroundLevel":
+		case "realTimeFollowSurface": return "realTimeFollowSurface";
+	}
+}
+//#endregion
+//#region src/plan/plan-mapping-strip.ts
+/**
+* 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.
+*/
+function planMappingStrip(template) {
+	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 = coords.map((c, index) => {
+		const headingAngle = index === coords.length - 1 ? 0 : bearingDeg(enuPath[index], enuPath[index + 1]);
+		const executeHeight = folder.stripUseTemplateAltitude && c.alt !== void 0 ? c.alt : 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 = {
+		templateId: folder.templateId,
+		waylineId: 0,
+		executeHeightMode: heightModeToExecuteMode$1(folder),
+		autoFlightSpeed: folder.autoFlightSpeed,
+		Placemark: placemarks
+	};
+	return {
+		missionConfig: template.missionConfig,
+		Folder: [waylineFolder]
+	};
+}
+function parseTriples(s) {
+	return s.trim().split(/\s+/).map((tuple) => {
+		const parts = tuple.split(",").map(Number);
+		return {
+			lng: parts[0],
+			lat: parts[1],
+			...parts[2] !== void 0 ? { alt: parts[2] } : {}
+		};
+	});
+}
+function heightModeToExecuteMode$1(folder) {
+	switch (folder.waylineCoordinateSysParam.heightMode) {
+		case "EGM96": return "WGS84";
+		case "relativeToStartPoint": return "relativeToStartPoint";
+		case "aboveGroundLevel":
+		case "realTimeFollowSurface": return "realTimeFollowSurface";
+	}
+}
+//#endregion
+//#region src/plan/plan-waypoint.ts
+/**
+* Compile a `waypoint` template directly: each Placemark in the template becomes
+* one waypoint in the wayline, resolving `useGlobalXxx` flags against folder defaults.
+*/
+function planWaypoint(template) {
+	const folder = template.Folder;
+	const placemarks = folder.Placemark.map((p, i) => {
+		const heading = p.useGlobalHeadingParam || p.waypointHeadingParam === void 0 ? folder.globalWaypointHeadingParam : p.waypointHeadingParam;
+		const turn = p.useGlobalTurnParam || p.waypointTurnParam === void 0 ? { waypointTurnMode: folder.globalWaypointTurnMode } : p.waypointTurnParam;
+		const executeHeight = p.useGlobalHeight || p.height === void 0 ? folder.globalHeight : p.height;
+		const waypointSpeed = p.useGlobalSpeed || p.waypointSpeed === void 0 ? folder.autoFlightSpeed : p.waypointSpeed;
+		return {
+			Point: p.Point,
+			index: i,
+			executeHeight,
+			waypointSpeed,
+			waypointHeadingParam: heading,
+			waypointTurnParam: turn,
+			...p.useStraightLine !== void 0 ? { useStraightLine: p.useStraightLine } : {},
+			...p.isRisky !== void 0 ? { isRisky: p.isRisky } : {},
+			...p.actionGroup !== void 0 ? { actionGroup: p.actionGroup } : {}
+		};
+	});
+	const waylineFolder = {
+		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) {
+	switch (mode) {
+		case "EGM96": return "WGS84";
+		case "relativeToStartPoint": return "relativeToStartPoint";
+		case "aboveGroundLevel":
+		case "realTimeFollowSurface": return "realTimeFollowSurface";
+	}
+}
+//#endregion
+//#region src/plan/index.ts
+const isWaypoint = (t) => t.Folder.templateType === "waypoint";
+const isMapping2d = (t) => t.Folder.templateType === "mapping2d";
+const isMapping3d = (t) => t.Folder.templateType === "mapping3d";
+const isMappingStrip = (t) => t.Folder.templateType === "mappingStrip";
+/**
+* Compile a high-level `Template` into executable `Waylines`.
+* Dispatch is by `template.Folder.templateType` per the DJI WPML spec.
+*/
+function plan(template) {
+	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.Folder.templateType}`);
+}
+//#endregion
+//#region src/validate/validate-mission-config.ts
+function validateMissionConfig(config, path) {
+	const issues = [];
+	if (config.exitOnRCLost === "executeLostAction" && config.executeRCLostAction === void 0) 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;
+}
+//#endregion
+//#region src/validate/validate-template.ts
+function validateTemplate(template) {
+	const folder = template.Folder;
+	const issues = [];
+	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, path));
+			break;
+		case "mapping2d":
+			issues.push(...validateMapping2dFolder(template, path));
+			break;
+		case "mapping3d":
+			issues.push(...validateMapping3dFolder(template, path));
+			break;
+		case "mappingStrip":
+			issues.push(...validateMappingStripFolder(template, path));
+			break;
+	}
+	return issues;
+}
+function validateWaypointFolder(t, path) {
+	const issues = [];
+	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, path) {
+	return validatePolygonRing(t.Folder.Placemark.Polygon.outerBoundaryIs.LinearRing.coordinates, `${path}.Placemark.Polygon`);
+}
+function validateMapping3dFolder(t, path) {
+	return validatePolygonRing(t.Folder.Placemark.Polygon.outerBoundaryIs.LinearRing.coordinates, `${path}.Placemark.Polygon`);
+}
+function validateMappingStripFolder(t, path) {
+	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, path) {
+	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 [];
+}
+//#endregion
+//#region src/validate/validate-waylines.ts
+function validateWaylines(waylines) {
+	const issues = [];
+	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, path) {
+	const issues = [];
+	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;
+}
+//#endregion
+//#region src/validate/index.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.
+*/
+function validate(doc) {
+	const issues = [];
+	issues.push(...validateMissionConfig(doc.missionConfig, "missionConfig"));
+	if ("Folder" in doc && Array.isArray(doc.Folder)) issues.push(...validateWaylines(doc));
+	else issues.push(...validateTemplate(doc));
+	return issues;
+}
+//#endregion
+export { DroneEnum, KmzError, PayloadEnum, PlannerError, degrees, meters, metersPerSecond, plan, validate };