@lumikmz/kmz 0.2.1 → 0.4.0

package/dist/index.mjs

@@ -81,46 +81,57 @@ const DroneEnum = {
 const PayloadEnum = {
 	M30Camera: {
 		payloadEnumValue: 52,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M30TCamera: {
 		payloadEnumValue: 53,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M3ECamera: {
 		payloadEnumValue: 66,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M3TCamera: {
 		payloadEnumValue: 67,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M3TACamera: {
 		payloadEnumValue: 129,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M3DCamera: {
 		payloadEnumValue: 80,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M3TDCamera: {
 		payloadEnumValue: 81,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M4DCamera: {
 		payloadEnumValue: 98,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M4TDCamera: {
 		payloadEnumValue: 99,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M4ECamera: {
 		payloadEnumValue: 88,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	M4TCamera: {
 		payloadEnumValue: 89,
+		payloadSubEnumValue: 0,
 		payloadPositionIndex: 0
 	},
 	ZenmuseZ30: {
@@ -207,6 +218,27 @@ function centroid(points) {
 function bearingDeg(from, to) {
 	return Math.atan2(to[0] - from[0], to[1] - from[1]) * RAD2DEG;
 }
+/**
+* Orient an ordered survey path so its first point is the end nearest `home`.
+* A boustrophedon grid has two natural entry ends; the aircraft should start at
+* whichever is closer to the take-off point. Returns the input unchanged when
+* `home` is absent or the start is already the nearer end.
+*/
+function orientPathToHome(enuWps, origin, home) {
+	if (!home || enuWps.length < 2) return enuWps;
+	const h = lngLatToEnu(home, origin);
+	const sqDist = (p) => (p[0] - h[0]) ** 2 + (p[1] - h[1]) ** 2;
+	return sqDist(enuWps[enuWps.length - 1]) < sqDist(enuWps[0]) ? [...enuWps].reverse() : enuWps;
+}
+/** Great-circle distance between two WGS-84 coordinates, in meters. */
+function haversineMeters(a, b) {
+	const dLat = (b.lat - a.lat) * DEG2RAD;
+	const dLng = (b.lng - a.lng) * DEG2RAD;
+	const lat1 = a.lat * DEG2RAD;
+	const lat2 = b.lat * DEG2RAD;
+	const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
+	return EARTH_RADIUS * 2 * Math.atan2(Math.sqrt(h), Math.sqrt(1 - h));
+}
 /** Clip a horizontal scan line `y = const` against a polygon; returns `[x_enter, x_exit]` pairs. */
 function clipHorizontal(y, polygon) {
 	const intersections = [];
@@ -224,24 +256,6 @@ function clipHorizontal(y, polygon) {
 	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).
@@ -255,211 +269,672 @@ function parseCoordinatesString(s) {
 		};
 	});
 }
+/** Rotate an ENU point counter-clockwise by `rad` radians about the origin. */
+function rotateEnu([x, y], rad) {
+	const c = Math.cos(rad);
+	const s = Math.sin(rad);
+	return [x * c - y * s, x * s + y * c];
+}
+/** Drop a closing duplicate and any consecutive vertices closer than `epsM`. */
+function dedupeRing(ring, epsM = .5) {
+	const pts = [];
+	for (const p of ring) {
+		const last = pts[pts.length - 1];
+		if (last && Math.hypot(p[0] - last[0], p[1] - last[1]) < epsM) continue;
+		pts.push([p[0], p[1]]);
+	}
+	const f = pts[0];
+	const l = pts[pts.length - 1];
+	if (pts.length >= 2 && f && l && Math.hypot(f[0] - l[0], f[1] - l[1]) < epsM) pts.pop();
+	return pts;
+}
+/** Beyond this multiple of `distM`, a corner miter is clamped to avoid spikes. */
+const OFFSET_MITER_LIMIT = 2.5;
+/**
+* Outward-offset (dilate) a simple polygon ring by `distM` meters in ENU.
+* Each vertex moves along the bisector of its two adjacent outward edge normals
+* by `distM / cos(halfAngle)`, clamped by a miter limit. The bisector form is
+* stable when adjacent edges are near-collinear (where edge-intersection would
+* shoot a spike far outward); the clamp bounds sharp corners; degenerate/duplicate
+* vertices are removed first. Intended for convex-ish survey areas.
+*/
+function offsetPolygon(ring, distM) {
+	const pts = dedupeRing(ring);
+	const n = pts.length;
+	if (distM === 0 || n < 3) return pts;
+	let area2 = 0;
+	for (let i = 0; i < n; i++) {
+		const a = pts[i];
+		const b = pts[(i + 1) % n];
+		area2 += a[0] * b[1] - b[0] * a[1];
+	}
+	const ccw = area2 > 0;
+	const outwardNormal = (dx, dy) => ccw ? [dy, -dx] : [-dy, dx];
+	const out = [];
+	for (let i = 0; i < n; i++) {
+		const prev = pts[(i - 1 + n) % n];
+		const cur = pts[i];
+		const next = pts[(i + 1) % n];
+		const inLen = Math.hypot(cur[0] - prev[0], cur[1] - prev[1]) || 1;
+		const outLen = Math.hypot(next[0] - cur[0], next[1] - cur[1]) || 1;
+		const nIn = outwardNormal((cur[0] - prev[0]) / inLen, (cur[1] - prev[1]) / inLen);
+		const nOut = outwardNormal((next[0] - cur[0]) / outLen, (next[1] - cur[1]) / outLen);
+		let bx = nIn[0] + nOut[0];
+		let by = nIn[1] + nOut[1];
+		const bl = Math.hypot(bx, by);
+		if (bl < 1e-9) {
+			out.push([cur[0] + nOut[0] * distM, cur[1] + nOut[1] * distM]);
+			continue;
+		}
+		bx /= bl;
+		by /= bl;
+		const cosHalf = nOut[0] * bx + nOut[1] * by;
+		const scale = distM / Math.max(cosHalf, 1 / OFFSET_MITER_LIMIT);
+		out.push([cur[0] + bx * scale, cur[1] + by * scale]);
+	}
+	return out;
+}
+/**
+* Boustrophedon survey grid over an arbitrary simple polygon, aligned to `directionDeg`.
+* Flight lines run parallel to the heading; consecutive lines step by `lineSpacing`.
+* `marginM` extends each line lengthwise past the polygon edge.
+* Returns ENU waypoints in flight order — no transit/entry point
+* (entry climb is a missionConfig behaviour, not a grid concern).
+*/
+function surveyGrid(ring, opts) {
+	const { directionDeg, marginM, lineSpacing, phaseOffsetM = 0, lengthwiseShiftM = 0 } = opts;
+	const t = directionDeg * DEG2RAD;
+	const alpha = Math.atan2(Math.cos(t), Math.sin(t));
+	const scanRing = ring.map((p) => rotateEnu(p, -alpha));
+	let minY = Infinity;
+	let maxY = -Infinity;
+	for (const [, y] of scanRing) {
+		if (y < minY) minY = y;
+		if (y > maxY) maxY = y;
+	}
+	const scanPts = [];
+	let leftToRight = true;
+	for (let y = minY + phaseOffsetM; y <= maxY + lineSpacing * .5; y += lineSpacing) {
+		for (const [x1, x2] of clipHorizontal(y, scanRing)) {
+			const a = x1 - marginM + lengthwiseShiftM;
+			const b = x2 + marginM + lengthwiseShiftM;
+			if (leftToRight) scanPts.push([a, y], [b, y]);
+			else scanPts.push([b, y], [a, y]);
+		}
+		leftToRight = !leftToRight;
+	}
+	return scanPts.map((p) => rotateEnu(p, alpha));
+}
 //#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) {
+/**
+* `standoffM` dilates the survey polygon outward before gridding (smart-oblique
+* needs the grid to overfly the boundary on every side; 0 for ortho/quick-ortho).
+*/
+function buildGrid(template, lineSpacing, standoffM = 0) {
 	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,
+	const enuRing = ring.map((p) => lngLatToEnu(p, origin));
+	return {
+		folder,
+		origin,
+		enuWps: orientPathToHome(surveyGrid(standoffM > 0 ? offsetPolygon(enuRing, standoffM) : enuRing, {
+			directionDeg: folder.Placemark.direction,
+			marginM: folder.Placemark.margin,
+			lineSpacing
+		}), origin, template.missionConfig.takeOffRefPoint)
+	};
+}
+/**
+* Smart-oblique stand-off (meters). The gimbal swings up to |swing|° off nadir in
+* all directions during a single pass, so the most-oblique look images h·tan(|swing|)
+* away from the aircraft. The survey polygon is therefore dilated by this distance so
+* the grid overflies the boundary on every side. Clamp to 3·h.
+*/
+function smartObliqueStandoff(folder) {
+	const h = Number(folder.Placemark.height);
+	const swingAbs = Math.abs(Number(folder.Placemark.smartObliqueGimbalPitch ?? degrees(-45)));
+	if (!(swingAbs > 0 && swingAbs < 90)) return 0;
+	return Math.min(h * Math.tan(swingAbs * Math.PI / 180), h * 3);
+}
+function heightModeToExecuteMode$3(folder) {
+	switch (folder.waylineCoordinateSysParam.heightMode) {
+		case "EGM96": return "WGS84";
+		case "relativeToStartPoint": return "relativeToStartPoint";
+		case "aboveGroundLevel":
+		case "realTimeFollowSurface": return "realTimeFollowSurface";
+	}
+}
+/** Desired damping distance; clamped down when segments are short. */
+const DESIRED_TURN_DAMPING_M = 10;
+/** Never consume more than this fraction of either adjacent segment. */
+const MAX_DAMPING_FRAC = .45;
+/** Flat ENU distance between two grid points (metres). */
+function enuSegLen(a, b) {
+	return Math.hypot(b[0] - a[0], b[1] - a[1]);
+}
+/**
+* Compute the coordinateTurn damping distance for interior waypoint `i`.
+*
+* Spec constraint: dampingDist[i] + dampingDist[i+1] < segmentLength(i, i+1).
+* Clamping each side to MAX_DAMPING_FRAC × its shorter adjacent segment
+* guarantees the sum is at most 2 × MAX_DAMPING_FRAC < 1 of that segment.
+*/
+function turnDamping(enuWps, i) {
+	const dPrev = enuSegLen(enuWps[i - 1], enuWps[i]);
+	const dNext = enuSegLen(enuWps[i], enuWps[i + 1]);
+	return meters(Math.min(DESIRED_TURN_DAMPING_M, dPrev * MAX_DAMPING_FRAC, dNext * MAX_DAMPING_FRAC));
+}
+/** Nadir gimbal-down, hover, manual focus, infinite focus, hover — per reference WPML. */
+function buildStartActionGroup(pitchDeg) {
+	return { action: [
+		{
+			actionId: 0,
+			actionActuatorFunc: "gimbalRotate",
+			actionActuatorFuncParam: {
+				payloadPositionIndex: 0,
+				gimbalHeadingYawBase: "aircraft",
+				gimbalRotateMode: "absoluteAngle",
+				gimbalPitchRotateEnable: true,
+				gimbalPitchRotateAngle: degrees(pitchDeg),
+				gimbalRollRotateEnable: false,
+				gimbalRollRotateAngle: degrees(0),
+				gimbalYawRotateEnable: true,
+				gimbalYawRotateAngle: degrees(0),
+				gimbalRotateTimeEnable: false,
+				gimbalRotateTime: 10
+			}
+		},
+		{
+			actionId: 1,
+			actionActuatorFunc: "hover",
+			actionActuatorFuncParam: { hoverTime: .5 }
+		},
+		{
+			actionId: 2,
+			actionActuatorFunc: "setFocusType",
+			actionActuatorFuncParam: {
+				payloadPositionIndex: 0,
+				cameraFocusType: "manual"
+			}
+		},
+		{
+			actionId: 3,
+			actionActuatorFunc: "focus",
+			actionActuatorFuncParam: {
+				payloadPositionIndex: 0,
+				isPointFocus: false,
+				focusX: 0,
+				focusY: 0,
+				focusRegionWidth: 0,
+				focusRegionHeight: 0,
+				isInfiniteFocus: true,
+				isCalibrationFocus: false
+			}
+		},
+		{
+			actionId: 4,
+			actionActuatorFunc: "hover",
+			actionActuatorFuncParam: { hoverTime: 1 }
+		}
+	] };
+}
+/** Build the three actions placed at the first waypoint of a shooting section. */
+function shootSectionStartActions(pitchDeg, shootInterval, sectionStart, sectionEnd, groupIdStart) {
+	return {
+		groups: [{
+			actionGroupId: groupIdStart,
+			actionGroupStartIndex: sectionStart,
+			actionGroupEndIndex: sectionEnd,
 			actionGroupMode: "sequence",
 			actionTrigger: { actionTriggerType: "betweenAdjacentPoints" },
+			action: [
+				{
+					actionId: 0,
+					actionActuatorFunc: "gimbalAngleLock",
+					actionActuatorFuncParam: { payloadPositionIndex: 0 }
+				},
+				{
+					actionId: 1,
+					actionActuatorFunc: "gimbalRotate",
+					actionActuatorFuncParam: {
+						payloadPositionIndex: 0,
+						gimbalHeadingYawBase: "aircraft",
+						gimbalRotateMode: "absoluteAngle",
+						gimbalPitchRotateEnable: true,
+						gimbalPitchRotateAngle: degrees(pitchDeg),
+						gimbalRollRotateEnable: false,
+						gimbalRollRotateAngle: degrees(0),
+						gimbalYawRotateEnable: false,
+						gimbalYawRotateAngle: degrees(0),
+						gimbalRotateTimeEnable: false,
+						gimbalRotateTime: 10
+					}
+				},
+				{
+					actionId: 2,
+					actionActuatorFunc: "startTimeLapse",
+					actionActuatorFuncParam: {
+						payloadPositionIndex: 0,
+						useGlobalPayloadLensIndex: false,
+						payloadLensIndex: "visable",
+						minShootInterval: shootInterval
+					}
+				}
+			]
+		}, {
+			actionGroupId: groupIdStart + 1,
+			actionGroupStartIndex: sectionStart,
+			actionGroupEndIndex: sectionEnd,
+			actionGroupMode: "sequence",
+			actionTrigger: {
+				actionTriggerType: "multipleTiming",
+				actionTriggerParam: shootInterval
+			},
 			action: [{
 				actionId: 0,
-				actionActuatorFunc: "takePhoto",
+				actionActuatorFunc: "gimbalRotate",
 				actionActuatorFuncParam: {
 					payloadPositionIndex: 0,
-					payloadLensIndex: ["wide"],
-					useGlobalPayloadLensIndex: false
+					gimbalHeadingYawBase: "aircraft",
+					gimbalRotateMode: "absoluteAngle",
+					gimbalPitchRotateEnable: true,
+					gimbalPitchRotateAngle: degrees(pitchDeg),
+					gimbalRollRotateEnable: false,
+					gimbalRollRotateAngle: degrees(0),
+					gimbalYawRotateEnable: false,
+					gimbalYawRotateAngle: degrees(0),
+					gimbalRotateTimeEnable: false,
+					gimbalRotateTime: 10
 				}
 			}]
-		}];
-		return {
+		}],
+		nextGroupId: groupIdStart + 2
+	};
+}
+/** Build the stop group placed at the last waypoint of a shooting section. */
+function shootSectionStopActions(sectionEnd, groupId) {
+	return {
+		actionGroupId: groupId,
+		actionGroupStartIndex: sectionEnd,
+		actionGroupEndIndex: sectionEnd,
+		actionGroupMode: "sequence",
+		actionTrigger: { actionTriggerType: "reachPoint" },
+		action: [{
+			actionId: 0,
+			actionActuatorFunc: "stopTimeLapse",
+			actionActuatorFuncParam: {
+				payloadPositionIndex: 0,
+				payloadLensIndex: "visable"
+			}
+		}, {
+			actionId: 1,
+			actionActuatorFunc: "gimbalAngleUnlock"
+		}]
+	};
+}
+/** Zero-dampingDist stop-turn (first/last waypoint of a section). */
+function stopTurn() {
+	return {
+		waypointTurnMode: "toPointAndStopWithDiscontinuityCurvature",
+		waypointTurnDampingDist: meters(0)
+	};
+}
+/** Common heading param fields present on every mapping waypoint. */
+function mappingHeadingParam(headingAngle, angleEnable) {
+	return {
+		waypointHeadingMode: "followWayline",
+		waypointHeadingAngle: degrees(headingAngle),
+		waypointPoiPoint: {
+			lng: 0,
+			lat: 0,
+			height: meters(0)
+		},
+		waypointHeadingAngleEnable: angleEnable,
+		waypointHeadingPathMode: "followBadArc",
+		waypointHeadingPoiIndex: 0
+	};
+}
+/** Common extra fields present on every mapping waypoint per reference WPML. */
+const COMMON_WP_EXTRAS = {
+	useStraightLine: true,
+	waypointGimbalHeadingParam: {
+		waypointGimbalPitchAngle: degrees(0),
+		waypointGimbalYawAngle: degrees(0)
+	},
+	isRisky: false,
+	waypointWorkType: 0
+};
+/**
+* 高程优化 (elevationOptimizeEnable) excursion — appended to the nadir grid:
+* fly from the last nadir waypoint to the survey centroid and take an oblique shot
+* there to enrich the DSM. WITHOUT this flag the route ends at the last grid
+* waypoint — it does NOT detour to the centre (that detour is elevation optimization,
+* not smart-swing). Mutates `placemarks` (appends two waypoints).
+*/
+function appendElevationExcursion(placemarks, folder, origin, enuWps, shootInterval, startGroupId) {
+	const lastNadirIdx = enuWps.length - 1;
+	const obliqueStartIdx = placemarks.length;
+	const obliqueEndIdx = obliqueStartIdx + 1;
+	const pitch = Number(folder.Placemark.quickOrthoMappingPitch ?? degrees(-45));
+	let nextGroupId = startGroupId;
+	const obliqueGimbalGroup = {
+		actionGroupId: nextGroupId++,
+		actionGroupStartIndex: obliqueStartIdx,
+		actionGroupEndIndex: obliqueStartIdx,
+		actionGroupMode: "sequence",
+		actionTrigger: { actionTriggerType: "reachPoint" },
+		action: [{
+			actionId: 0,
+			actionActuatorFunc: "gimbalRotate",
+			actionActuatorFuncParam: {
+				payloadPositionIndex: 0,
+				gimbalHeadingYawBase: "aircraft",
+				gimbalRotateMode: "absoluteAngle",
+				gimbalPitchRotateEnable: true,
+				gimbalPitchRotateAngle: degrees(pitch),
+				gimbalRollRotateEnable: false,
+				gimbalRollRotateAngle: degrees(0),
+				gimbalYawRotateEnable: true,
+				gimbalYawRotateAngle: degrees(0),
+				gimbalRotateTimeEnable: false,
+				gimbalRotateTime: 10
+			}
+		}, {
+			actionId: 1,
+			actionActuatorFunc: "hover",
+			actionActuatorFuncParam: { hoverTime: .5 }
+		}]
+	};
+	const obliqueStart = shootSectionStartActions(pitch, shootInterval, obliqueStartIdx, obliqueEndIdx, nextGroupId);
+	nextGroupId = obliqueStart.nextGroupId;
+	const obliqueStop = shootSectionStopActions(obliqueEndIdx, nextGroupId);
+	const lastNadirCoord = enuToLngLat(enuWps[lastNadirIdx], origin);
+	const sumEnu = enuWps.reduce((acc, p) => [acc[0] + p[0], acc[1] + p[1]], [0, 0]);
+	const centroidEnu = [sumEnu[0] / enuWps.length, sumEnu[1] / enuWps.length];
+	const centroidCoord = enuToLngLat(centroidEnu, origin);
+	const obliqueHeading = bearingDeg(enuWps[lastNadirIdx], centroidEnu);
+	placemarks.push({
+		Point: { coordinates: lastNadirCoord },
+		index: obliqueStartIdx,
+		executeHeight: folder.Placemark.height,
+		waypointSpeed: folder.autoFlightSpeed,
+		waypointHeadingParam: mappingHeadingParam(obliqueHeading, true),
+		waypointTurnParam: stopTurn(),
+		...COMMON_WP_EXTRAS,
+		actionGroup: [obliqueGimbalGroup, ...obliqueStart.groups]
+	});
+	placemarks.push({
+		Point: { coordinates: centroidCoord },
+		index: obliqueEndIdx,
+		executeHeight: folder.Placemark.height,
+		waypointSpeed: folder.autoFlightSpeed,
+		waypointHeadingParam: mappingHeadingParam(0, false),
+		waypointTurnParam: stopTurn(),
+		...COMMON_WP_EXTRAS,
+		actionGroup: [obliqueStop]
+	});
+}
+/**
+* Ortho (nadir) wayline — covers 正射 and 正射+智能摆拍 (the swing is a folder-level
+* quickOrthoMappingEnable flag over the same grid geometry, not extra waypoints).
+*
+* Action pattern (per reference WPML M4TD 正射采集):
+*   - WP 0: two action groups (betweenAdjacentPoints startTimeLapse-init + multipleTiming gimbalCorrect)
+*   - WP 1…N-2: no action groups
+*   - WP N-1 (last): reachPoint stopTimeLapse group
+*
+* When `elevationOptimizeEnable` is set, a centroid excursion is appended (see
+* `appendElevationExcursion`); otherwise the route ends at the last grid waypoint.
+*/
+function emitOrtho(folder, origin, enuWps, shootInterval) {
+	const lastIndex = enuWps.length - 1;
+	const startActions = shootSectionStartActions(-90, shootInterval, 0, lastIndex, 0);
+	const stopGroup = shootSectionStopActions(lastIndex, startActions.nextGroupId);
+	const placemarks = enuWps.map((enu, index) => {
+		const coord = enuToLngLat(enu, origin);
+		const isLast = index === lastIndex;
+		const headingAngle = isLast ? 0 : bearingDeg(enuWps[index], enuWps[index + 1]);
+		const placemark = {
 			Point: { coordinates: coord },
 			index,
-			executeHeight: folder.height,
+			executeHeight: folder.Placemark.height,
 			waypointSpeed: folder.autoFlightSpeed,
-			waypointHeadingParam: {
-				waypointHeadingMode: "followWayline",
-				waypointHeadingAngle: degrees(headingAngle),
-				waypointHeadingPathMode: "followBadArc"
+			waypointHeadingParam: mappingHeadingParam(headingAngle, !isLast),
+			waypointTurnParam: index === 0 || isLast ? stopTurn() : {
+				waypointTurnMode: "coordinateTurn",
+				waypointTurnDampingDist: turnDamping(enuWps, index)
 			},
-			waypointTurnParam: { waypointTurnMode: "toPointAndPassWithContinuityCurvature" },
-			...actionGroup.length > 0 ? { actionGroup } : {}
+			...COMMON_WP_EXTRAS
 		};
+		if (index === 0) placemark.actionGroup = startActions.groups;
+		else if (isLast) placemark.actionGroup = [stopGroup];
+		return placemark;
 	});
-	const waylineFolder = {
+	if (folder.Placemark.elevationOptimizeEnable) appendElevationExcursion(placemarks, folder, origin, enuWps, shootInterval, startActions.nextGroupId + 1);
+	return {
 		templateId: folder.templateId,
 		waylineId: 0,
 		executeHeightMode: heightModeToExecuteMode$3(folder),
 		autoFlightSpeed: folder.autoFlightSpeed,
-		startActionGroup: {
-			actionGroupId: 65535,
+		startActionGroup: buildStartActionGroup(-90),
+		Placemark: placemarks
+	};
+}
+/**
+* Single-pass smart-oblique / quick-ortho (smartObliqueEnable=true):
+* The aircraft flies one grid while the gimbal swings (startSmartOblique/stopSmartOblique).
+*/
+function emitSmartOblique(folder, origin, enuWps) {
+	const lastIndex = enuWps.length - 1;
+	const pitch = folder.Placemark.smartObliqueGimbalPitch ?? degrees(-45);
+	const placemarks = enuWps.map((enu, index) => {
+		const coord = enuToLngLat(enu, origin);
+		const isLast = index === lastIndex;
+		const headingAngle = isLast ? 0 : bearingDeg(enuWps[index], enuWps[index + 1]);
+		const placemark = {
+			Point: { coordinates: coord },
+			index,
+			executeHeight: folder.Placemark.height,
+			waypointSpeed: folder.autoFlightSpeed,
+			waypointHeadingParam: mappingHeadingParam(headingAngle, !isLast),
+			waypointTurnParam: index === 0 || isLast ? stopTurn() : {
+				waypointTurnMode: "coordinateTurn",
+				waypointTurnDampingDist: turnDamping(enuWps, index)
+			},
+			...COMMON_WP_EXTRAS
+		};
+		if (index === 0) placemark.actionGroup = [{
+			actionGroupId: 0,
 			actionGroupStartIndex: 0,
-			actionGroupEndIndex: 0,
+			actionGroupEndIndex: lastIndex,
 			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
-				}
+				actionActuatorFunc: "startSmartOblique",
+				actionActuatorFuncParam: { payloadPositionIndex: 0 }
 			}]
-		},
+		}];
+		else if (isLast) placemark.actionGroup = [{
+			actionGroupId: 1,
+			actionGroupStartIndex: lastIndex,
+			actionGroupEndIndex: lastIndex,
+			actionGroupMode: "sequence",
+			actionTrigger: { actionTriggerType: "reachPoint" },
+			action: [{
+				actionId: 0,
+				actionActuatorFunc: "stopSmartOblique",
+				actionActuatorFuncParam: { payloadPositionIndex: 0 }
+			}]
+		}];
+		return placemark;
+	});
+	return {
+		templateId: folder.templateId,
+		waylineId: 0,
+		executeHeightMode: heightModeToExecuteMode$3(folder),
+		autoFlightSpeed: folder.autoFlightSpeed,
+		startActionGroup: buildStartActionGroup(Number(pitch)),
 		Placemark: placemarks
 	};
+}
+function planMapping2d(template, options) {
+	if (options?.lineSpacing == null) throw new PlannerError("mapping2d requires options.lineSpacing — calculate 2·h·tan(HFOV/2)·(1−sideOverlap) in the demo and pass it in.");
+	const standoff = template.Folder.Placemark.smartObliqueEnable === true ? smartObliqueStandoff(template.Folder) : 0;
+	const { folder, origin, enuWps } = buildGrid(template, Number(options.lineSpacing), standoff);
+	const shootInterval = options.shootInterval ?? 2;
+	if (folder.Placemark.smartObliqueEnable === true) return {
+		missionConfig: template.missionConfig,
+		Folder: [emitSmartOblique(folder, origin, enuWps)]
+	};
 	return {
 		missionConfig: template.missionConfig,
-		Folder: [waylineFolder]
+		Folder: [emitOrtho(folder, origin, enuWps, shootInterval)]
 	};
 }
-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 PASSES = [
+	{
+		axisOffsetDeg: 0,
+		headingOffsetDeg: 0,
+		pitch: "nadir",
+		headingMode: "followWayline",
+		halfPhase: false,
+		lookSign: 0,
+		interval: 2
+	},
+	{
+		axisOffsetDeg: 0,
+		headingOffsetDeg: 0,
+		pitch: "inclined",
+		headingMode: "fixed",
+		halfPhase: false,
+		lookSign: 1,
+		interval: 2.5
+	},
+	{
+		axisOffsetDeg: 90,
+		headingOffsetDeg: 90,
+		pitch: "inclined",
+		headingMode: "fixed",
+		halfPhase: false,
+		lookSign: 1,
+		interval: 2.5
+	},
+	{
+		axisOffsetDeg: 0,
+		headingOffsetDeg: 180,
+		pitch: "inclined",
+		headingMode: "fixed",
+		halfPhase: true,
+		lookSign: -1,
+		interval: 2.5
+	},
+	{
+		axisOffsetDeg: 90,
+		headingOffsetDeg: -90,
+		pitch: "inclined",
+		headingMode: "fixed",
+		halfPhase: true,
+		lookSign: -1,
+		interval: 2.5
+	}
+];
+/** Normalize an angle to (−180, 180]. */
+function wrap180(deg) {
+	return ((deg + 180) % 360 + 360) % 360 - 180;
+}
+function planMapping3d(template, options) {
+	if (options?.lineSpacing == null) throw new PlannerError("mapping3d requires options.lineSpacing — calculate 2·h·tan(HFOV/2)·(1−sideOverlap) in the demo and pass it in.");
 	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));
+	const ringEnu = ring.map((p) => lngLatToEnu(p, origin));
+	const baseDirection = Number(folder.Placemark.direction);
+	const lineSpacing = Number(options.lineSpacing);
+	const inclined = folder.Placemark.inclinedGimbalPitch;
+	const pitchAbs = Math.abs(Number(inclined));
+	const sinP = pitchAbs > 0 && pitchAbs < 90 ? Math.sin(pitchAbs * Math.PI / 180) : 1;
+	const tanP = pitchAbs > 0 && pitchAbs < 90 ? Math.tan(pitchAbs * Math.PI / 180) : Infinity;
+	const standoff = Math.min(Number(folder.Placemark.height) / tanP, Number(folder.Placemark.height) * 3);
+	const obliqueSpacing = lineSpacing / sinP;
 	return {
 		missionConfig: template.missionConfig,
-		Folder
+		Folder: PASSES.map((pass, i) => {
+			const passSpacing = pass.pitch === "inclined" ? obliqueSpacing : lineSpacing;
+			return buildPass(folder, i, origin, orientPathToHome(surveyGrid(ringEnu, {
+				directionDeg: baseDirection + pass.axisOffsetDeg,
+				marginM: folder.Placemark.margin,
+				lineSpacing: passSpacing,
+				phaseOffsetM: pass.halfPhase ? passSpacing / 2 : 0,
+				lengthwiseShiftM: -pass.lookSign * standoff
+			}), origin, template.missionConfig.takeOffRefPoint), {
+				headingMode: pass.headingMode,
+				headingAngle: degrees(wrap180(baseDirection + pass.headingOffsetDeg)),
+				gimbalPitch: pass.pitch === "nadir" ? degrees(-90) : inclined,
+				interval: pass.interval
+			});
+		})
 	};
 }
-function buildObliquePass(folder, waylineId, origin, enuWps, headingAngle, gimbalPitch, minShootInterval) {
+function buildPass(folder, waylineId, origin, enuWps, cfg) {
 	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,
+			executeHeight: folder.Placemark.height,
+			waypointSpeed: folder.Placemark.inclinedFlightSpeed,
 			waypointHeadingParam: {
-				waypointHeadingMode: "fixed",
-				waypointHeadingAngle: degrees(headingAngle),
+				waypointHeadingMode: cfg.headingMode,
+				waypointHeadingAngle: cfg.headingAngle,
 				waypointHeadingPathMode: "followBadArc"
 			},
 			waypointTurnParam: { waypointTurnMode: "toPointAndPassWithContinuityCurvature" }
 		};
-		const groups = waypointActionGroups(index, lastIndex, gimbalPitch, minShootInterval);
-		if (groups.length > 0) placemark.actionGroup = groups;
+		if (index === 0) placemark.actionGroup = [{
+			actionGroupId: 0,
+			actionGroupStartIndex: 0,
+			actionGroupEndIndex: lastIndex,
+			actionGroupMode: "sequence",
+			actionTrigger: { actionTriggerType: "reachPoint" },
+			action: [gimbalRotate(0, cfg.gimbalPitch)]
+		}, {
+			actionGroupId: 1,
+			actionGroupStartIndex: 0,
+			actionGroupEndIndex: lastIndex,
+			actionGroupMode: "sequence",
+			actionTrigger: {
+				actionTriggerType: "multipleTiming",
+				actionTriggerParam: cfg.interval
+			},
+			action: [takePhoto(0)]
+		}];
 		return placemark;
 	});
 	return {
 		templateId: folder.templateId,
 		waylineId,
 		executeHeightMode: heightModeToExecuteMode$2(folder.waylineCoordinateSysParam.heightMode),
-		autoFlightSpeed: folder.autoFlightSpeed,
-		startActionGroup: startGimbalRotateGroup(gimbalPitch),
+		autoFlightSpeed: folder.Placemark.inclinedFlightSpeed,
+		startActionGroup: { action: [gimbalRotate(0, cfg.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)]
-	};
-}
+/** Oblique gimbal: pitched down relative to the aircraft nose (yaw base = aircraft). */
 function gimbalRotate(actionId, pitch) {
 	return {
 		actionId,
 		actionActuatorFunc: "gimbalRotate",
 		actionActuatorFuncParam: {
 			payloadPositionIndex: 0,
-			gimbalHeadingYawBase: "north",
+			gimbalHeadingYawBase: "aircraft",
 			gimbalRotateMode: "absoluteAngle",
 			gimbalPitchRotateEnable: true,
-			gimbalPitchRotateAngle: degrees(pitch),
+			gimbalPitchRotateAngle: pitch,
 			gimbalRollRotateEnable: false,
 			gimbalRollRotateAngle: degrees(0),
 			gimbalYawRotateEnable: false,
@@ -510,7 +985,7 @@ function planMappingStrip(template) {
 	}, 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;
+		const executeHeight = folder.Placemark.stripUseTemplateAltitude && c.alt !== void 0 ? c.alt : folder.Placemark.height;
 		return {
 			Point: { coordinates: {
 				lng: c.lng,
@@ -616,11 +1091,13 @@ 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.
+*
+* Mapping templates require `options.lineSpacing` (meters between flight lines).
 */
-function plan(template) {
+function plan(template, options) {
 	if (isWaypoint(template)) return planWaypoint(template);
-	if (isMapping2d(template)) return planMapping2d(template);
-	if (isMapping3d(template)) return planMapping3d(template);
+	if (isMapping2d(template)) return planMapping2d(template, options);
+	if (isMapping3d(template)) return planMapping3d(template, options);
 	if (isMappingStrip(template)) return planMappingStrip(template);
 	throw new PlannerError(`Unknown templateType: ${template.Folder.templateType}`);
 }
@@ -776,4 +1253,4 @@ function validate(doc) {
 	return issues;
 }
 //#endregion
-export { DroneEnum, KmzError, PayloadEnum, PlannerError, degrees, meters, metersPerSecond, plan, validate };
+export { DroneEnum, KmzError, PayloadEnum, PlannerError, degrees, haversineMeters, meters, metersPerSecond, plan, validate };