@lumikmz/kmz 0.9.0 → 0.10.0

package/dist/index.d.mts

@@ -36,7 +36,7 @@ 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 TemplateType = "waypoint" | "mapping2d" | "mapping3d" | "mappingStrip" | "targetdetection";
 type CoordinateMode = "WGS84";
 /** Used in template.kml `waylineCoordinateSysParam.heightMode`. */
 type TemplateHeightMode = "EGM96" | "relativeToStartPoint" | "aboveGroundLevel" | "realTimeFollowSurface";
@@ -58,7 +58,7 @@ type MeteringMode = "average" | "spot";
 type LidarReturnMode = "singleReturnStrongest" | "dualReturn" | "tripleReturn";
 type LidarScanningMode = "repetitive" | "nonRepetitive";
 type ActionGroupMode = "sequence";
-type ActionTriggerType = "reachPoint" | "betweenAdjacentPoints" | "multipleTiming" | "multipleDistance";
+type ActionTriggerType = "reachPoint" | "betweenAdjacentPoints" | "betweenAdjacentPointsIncludeFirstPoint" | "multipleTiming" | "multipleDistance";
 type ActionActuatorFunc = "takePhoto" | "startRecord" | "stopRecord" | "focus" | "zoom" | "customDirName" | "gimbalRotate" | "rotateYaw" | "hover" | "gimbalEvenlyRotate" | "accurateShoot" | "orientedShoot" | "panoShot" | "recordPointCloud" | "megaphone" | "searchlight" /** ⚠️ NON-SPEC — observed in real DJI KMZ exports, absent from WPML 1.15 docs. */ | "startSmartOblique" /** ⚠️ NON-SPEC — observed in real DJI KMZ exports, absent from WPML 1.15 docs. */ | "stopSmartOblique" /** Starts time-lapse (interval) shooting for a mapping strip. */ | "startTimeLapse" /** Stops time-lapse shooting. */ | "stopTimeLapse" /** Locks gimbal angle during a mapping strip. */ | "gimbalAngleLock" /** Unlocks gimbal angle (no params in XML). */ | "gimbalAngleUnlock" /** Sets camera focus mode (manual / auto). */ | "setFocusType";
 type GimbalHeadingYawBase = "north" | "aircraft";
 type GimbalRotateMode = "absoluteAngle";
@@ -264,6 +264,8 @@ interface MissionConfig {
   globalRTHHeight: Meters;
   droneInfo: DroneInfo;
   payloadInfo: PayloadInfo[];
+  /** FlightHub 2 custom restricted-area avoidance switch. */
+  waylineAvoidLimitAreaMode?: boolean;
   /** Only M3D/M3TD, M4D/M4TD, M4E/M4T. */
   autoRerouteInfo?: AutoRerouteInfo;
 }
@@ -749,6 +751,19 @@ interface Mapping3dPlacemark {
   ellipsoidHeight: Meters;
   height: Meters;
 }
+/** `Placemark` inside a FlightHub 2 patrol-area `targetdetection` Folder. */
+interface TargetDetectionPlacemark {
+  direction: Degrees;
+  margin: number;
+  gimbalPitchMode: "fixed";
+  overlap: Overlap;
+  Polygon: TemplatePolygon;
+  ellipsoidHeight: Meters;
+  height: Meters;
+  mappingHeadingParam: MappingHeadingParam;
+  gimbalPitchAngle: Degrees;
+  recordEnable: boolean;
+}
 /** `Placemark` inside a `mappingStrip` Folder — uses a LineString; params live here. */
 interface MappingStripPlacemark {
   caliFlightEnable: boolean;
@@ -810,7 +825,7 @@ interface WaylinesPlacemark {
  * `template.kml` document. Mirrors `<kml><Document>` structure.
  * See `docs/kmz/template-kml.html`.
  */
-type Template = WaypointTemplate | Mapping2dTemplate | Mapping3dTemplate | MappingStripTemplate;
+type Template = WaypointTemplate | Mapping2dTemplate | Mapping3dTemplate | MappingStripTemplate | TargetDetectionTemplate;
 interface TemplateDocumentBase {
   /** Unix milliseconds. */
   author?: string;
@@ -870,6 +885,17 @@ interface Mapping3dFolder {
   /** Holds the survey polygon AND all shooting/mapping params. */
   Placemark: Mapping3dPlacemark;
 }
+interface TargetDetectionTemplate extends TemplateDocumentBase {
+  Folder: TargetDetectionFolder;
+}
+interface TargetDetectionFolder {
+  templateType: "targetdetection";
+  templateId: number;
+  waylineCoordinateSysParam: WaylineCoordinateSysParam;
+  autoFlightSpeed: MetersPerSecond;
+  payloadParam?: PayloadParam;
+  Placemark: TargetDetectionPlacemark;
+}
 interface MappingStripTemplate extends TemplateDocumentBase {
   Folder: MappingStripFolder;
 }
@@ -940,6 +966,8 @@ interface PlanOptions {
   stripDirection?: "parallel" | "perpendicular";
   /** Reverse mappingStrip region execution without changing region identities. */
   regionOrderReversed?: boolean;
+  /** Preferred entry location for path variants that can be reversed as a whole. */
+  preferredStartPoint?: LngLat;
   resolveExecuteHeight?: (point: {
     lng: number;
     lat: number;
@@ -1003,4 +1031,4 @@ declare function validate(doc: Template | Waylines): Issue[];
 /** Great-circle distance between two WGS-84 coordinates, in meters. */
 declare function haversineMeters(a: LngLat, b: LngLat): number;
 //#endregion
-export { AccurateShootAction, AccurateShootParam, Action, ActionActuatorFunc, ActionGroup, ActionGroupMode, ActionTrigger, ActionTriggerType, AircraftPathMode, AutoRerouteInfo, CoordinateMode, CustomDirNameAction, CustomDirNameParam, Degrees, DroneEnum, DroneInfo, ExecuteHeightMode, ExecuteRCLostAction, ExitOnRCLost, FinishAction, FlyToWaylineMode, FocusAction, FocusMode, FocusParam, GimbalAngleLockAction, GimbalAngleLockParam, GimbalAngleUnlockAction, GimbalEvenlyRotateAction, GimbalEvenlyRotateParam, GimbalHeadingYawBase, GimbalPitchMode, GimbalRotateAction, GimbalRotateMode, GimbalRotateParam, HoverAction, HoverParam, Issue, KmzError, LensType, LidarReturnMode, LidarScanningMode, LngLat, LngLatHeight, Mapping2dFolder, Mapping2dPlacemark, Mapping2dTemplate, Mapping3dFolder, Mapping3dPlacemark, Mapping3dTemplate, MappingHeadingMode, MappingHeadingParam, type MappingStripDerived, MappingStripFolder, MappingStripPlacemark, type MappingStripRegion, type MappingStripRegionRoute, MappingStripTemplate, MegaphoneAction, MegaphoneParam, MegaphoneTtsParam, MeteringMode, Meters, MetersPerSecond, MissionConfig, OrientedPhotoMode, OrientedShootAction, OrientedShootParam, Overlap, PanoShotAction, PanoShotParam, PanoShotSubMode, PayloadEnum, PayloadInfo, PayloadParam, type PlanOptions, PlannerError, PositioningType, RecordPointCloudAction, RecordPointCloudOperate, RecordPointCloudParam, RotateYawAction, RotateYawParam, SearchlightAction, SearchlightParam, SetFocusTypeAction, SetFocusTypeParam, ShootType, SmartObliquePoint, StartActionGroup, StartRecordAction, StartRecordParam, StartSmartObliqueAction, StartSmartObliqueParam, StartTimeLapseAction, StartTimeLapseParam, StopRecordAction, StopRecordParam, StopSmartObliqueAction, StopSmartObliqueParam, StopTimeLapseAction, StopTimeLapseParam, TakePhotoAction, TakePhotoParam, Template, TemplateHeightMode, TemplatePolygon, TemplateType, TemplateWaypointPlacemark, WaylineCoordinateSysParam, Waylines, WaylinesFolder, WaylinesPlacemark, WaypointFolder, WaypointHeadingMode, WaypointHeadingParam, WaypointHeadingPathMode, WaypointTemplate, WaypointTurnMode, WaypointTurnParam, ZoomAction, ZoomParam, degrees, deriveMappingStrip, haversineMeters, meters, metersPerSecond, plan, validate };
+export { AccurateShootAction, AccurateShootParam, Action, ActionActuatorFunc, ActionGroup, ActionGroupMode, ActionTrigger, ActionTriggerType, AircraftPathMode, AutoRerouteInfo, CoordinateMode, CustomDirNameAction, CustomDirNameParam, Degrees, DroneEnum, DroneInfo, ExecuteHeightMode, ExecuteRCLostAction, ExitOnRCLost, FinishAction, FlyToWaylineMode, FocusAction, FocusMode, FocusParam, GimbalAngleLockAction, GimbalAngleLockParam, GimbalAngleUnlockAction, GimbalEvenlyRotateAction, GimbalEvenlyRotateParam, GimbalHeadingYawBase, GimbalPitchMode, GimbalRotateAction, GimbalRotateMode, GimbalRotateParam, HoverAction, HoverParam, Issue, KmzError, LensType, LidarReturnMode, LidarScanningMode, LngLat, LngLatHeight, Mapping2dFolder, Mapping2dPlacemark, Mapping2dTemplate, Mapping3dFolder, Mapping3dPlacemark, Mapping3dTemplate, MappingHeadingMode, MappingHeadingParam, type MappingStripDerived, MappingStripFolder, MappingStripPlacemark, type MappingStripRegion, type MappingStripRegionRoute, MappingStripTemplate, MegaphoneAction, MegaphoneParam, MegaphoneTtsParam, MeteringMode, Meters, MetersPerSecond, MissionConfig, OrientedPhotoMode, OrientedShootAction, OrientedShootParam, Overlap, PanoShotAction, PanoShotParam, PanoShotSubMode, PayloadEnum, PayloadInfo, PayloadParam, type PlanOptions, PlannerError, PositioningType, RecordPointCloudAction, RecordPointCloudOperate, RecordPointCloudParam, RotateYawAction, RotateYawParam, SearchlightAction, SearchlightParam, SetFocusTypeAction, SetFocusTypeParam, ShootType, SmartObliquePoint, StartActionGroup, StartRecordAction, StartRecordParam, StartSmartObliqueAction, StartSmartObliqueParam, StartTimeLapseAction, StartTimeLapseParam, StopRecordAction, StopRecordParam, StopSmartObliqueAction, StopSmartObliqueParam, StopTimeLapseAction, StopTimeLapseParam, TakePhotoAction, TakePhotoParam, TargetDetectionFolder, TargetDetectionPlacemark, TargetDetectionTemplate, Template, TemplateHeightMode, TemplatePolygon, TemplateType, TemplateWaypointPlacemark, WaylineCoordinateSysParam, Waylines, WaylinesFolder, WaylinesPlacemark, WaypointFolder, WaypointHeadingMode, WaypointHeadingParam, WaypointHeadingPathMode, WaypointTemplate, WaypointTurnMode, WaypointTurnParam, ZoomAction, ZoomParam, degrees, deriveMappingStrip, haversineMeters, meters, metersPerSecond, plan, validate };

package/dist/index.mjs

@@ -182,22 +182,22 @@ const PayloadEnum = {
 //#endregion
 //#region src/plan/geometry.ts
 const EARTH_RADIUS = 6371e3;
-const DEG2RAD = Math.PI / 180;
-const RAD2DEG = 180 / Math.PI;
+const DEG2RAD$1 = Math.PI / 180;
+const RAD2DEG$1 = 180 / Math.PI;
 const ANGLE_EPS_RAD = 1e-12;
 /** 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;
+	const dLat = (point.lat - origin.lat) * DEG2RAD$1;
+	const dLng = (point.lng - origin.lng) * DEG2RAD$1;
+	const avgLat = (point.lat + origin.lat) / 2 * DEG2RAD$1;
 	return [dLng * EARTH_RADIUS * Math.cos(avgLat), dLat * EARTH_RADIUS];
 }
 /** Inverse of `lngLatToEnu`. */
 function enuToLngLat([x, y], origin) {
-	const avgLat = origin.lat * DEG2RAD;
+	const avgLat = origin.lat * DEG2RAD$1;
 	return {
-		lng: origin.lng + x / (EARTH_RADIUS * Math.cos(avgLat)) * RAD2DEG,
-		lat: origin.lat + y / EARTH_RADIUS * RAD2DEG
+		lng: origin.lng + x / (EARTH_RADIUS * Math.cos(avgLat)) * RAD2DEG$1,
+		lat: origin.lat + y / EARTH_RADIUS * RAD2DEG$1
 	};
 }
 function centroid(points) {
@@ -217,7 +217,7 @@ function centroid(points) {
 * ENU axes: x=east, y=north.
 */
 function bearingDeg(from, to) {
-	return Math.atan2(to[0] - from[0], to[1] - from[1]) * RAD2DEG;
+	return Math.atan2(to[0] - from[0], to[1] - from[1]) * RAD2DEG$1;
 }
 /**
 * Orient an ordered survey path so its first point is the end nearest `home`.
@@ -233,10 +233,10 @@ function orientPathToHome(enuWps, origin, home) {
 }
 /** 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 dLat = (b.lat - a.lat) * DEG2RAD$1;
+	const dLng = (b.lng - a.lng) * DEG2RAD$1;
+	const lat1 = a.lat * DEG2RAD$1;
+	const lat2 = b.lat * DEG2RAD$1;
 	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));
 }
@@ -367,7 +367,7 @@ function stabilizeTurnCorridors(segments) {
 */
 function surveyGrid(ring, opts) {
 	const { directionDeg, marginM, lineSpacing, phaseOffsetM = 0, lengthwiseShiftM = 0 } = opts;
-	const t = directionDeg * DEG2RAD;
+	const t = directionDeg * DEG2RAD$1;
 	const rawAlpha = Math.atan2(Math.cos(t), Math.sin(t));
 	const alpha = Math.abs(rawAlpha) < ANGLE_EPS_RAD ? 0 : rawAlpha;
 	const scanRing = ring.map((p) => rotateEnu(p, -alpha));
@@ -461,7 +461,7 @@ function enuSegLen(a, b) {
 * 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$1(enuWps, i) {
+function turnDamping$2(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));
@@ -744,7 +744,7 @@ function emitOrtho(folder, origin, enuWps, shootInterval, options) {
 			waypointHeadingParam: mappingHeadingParam(headingAngle, !isLast),
 			waypointTurnParam: index === 0 || isLast ? stopTurn() : {
 				waypointTurnMode: "coordinateTurn",
-				waypointTurnDampingDist: turnDamping$1(enuWps, index)
+				waypointTurnDampingDist: turnDamping$2(enuWps, index)
 			},
 			...COMMON_WP_EXTRAS
 		};
@@ -783,7 +783,7 @@ function emitSmartOblique(folder, origin, enuWps, shootInterval, options) {
 			waypointHeadingParam: mappingHeadingParam(headingAngle, !isLast),
 			waypointTurnParam: index === 0 || isLast ? stopTurn() : {
 				waypointTurnMode: "coordinateTurn",
-				waypointTurnDampingDist: turnDamping$1(enuWps, index)
+				waypointTurnDampingDist: turnDamping$2(enuWps, index)
 			},
 			...COMMON_WP_EXTRAS
 		};
@@ -1507,7 +1507,7 @@ function heightModeToExecuteMode$1(folder) {
 		case "realTimeFollowSurface": return "realTimeFollowSurface";
 	}
 }
-function turnDamping(points, index) {
+function turnDamping$1(points, index) {
 	const previous = haversineMeters(points[index - 1], points[index]);
 	const next = haversineMeters(points[index], points[index + 1]);
 	return meters(Math.min(TURN_DAMPING_M, previous * .45, next * .45));
@@ -1755,7 +1755,7 @@ function planMappingStrip(template, options) {
 					waypointTurnDampingDist: meters(0)
 				} : {
 					waypointTurnMode: "coordinateTurn",
-					waypointTurnDampingDist: turnDamping(points, index)
+					waypointTurnDampingDist: turnDamping$1(points, index)
 				},
 				useStraightLine: true,
 				isRisky: false,
@@ -1826,11 +1826,157 @@ function heightModeToExecuteMode(mode) {
 	}
 }
 //#endregion
+//#region src/plan/plan-target-detection.ts
+const EARTH_RADIUS_M = 6378137;
+const DEG2RAD = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+function project({ lng, lat }) {
+	return [EARTH_RADIUS_M * lng * DEG2RAD, EARTH_RADIUS_M * Math.log(Math.tan(Math.PI / 4 + lat * DEG2RAD / 2))];
+}
+function unproject([x, y]) {
+	return {
+		lng: x / EARTH_RADIUS_M * RAD2DEG,
+		lat: (2 * Math.atan(Math.exp(y / EARTH_RADIUS_M)) - Math.PI / 2) * RAD2DEG
+	};
+}
+function executeHeightMode(folder) {
+	switch (folder.waylineCoordinateSysParam.heightMode) {
+		case "EGM96": return "WGS84";
+		case "relativeToStartPoint": return "relativeToStartPoint";
+		case "aboveGroundLevel":
+		case "realTimeFollowSurface": return "realTimeFollowSurface";
+	}
+}
+function gimbalAction(pitch) {
+	return {
+		actionId: 0,
+		actionActuatorFunc: "gimbalRotate",
+		actionActuatorFuncParam: {
+			payloadPositionIndex: 0,
+			gimbalHeadingYawBase: "aircraft",
+			gimbalRotateMode: "absoluteAngle",
+			gimbalPitchRotateEnable: true,
+			gimbalPitchRotateAngle: degrees(pitch),
+			gimbalRollRotateEnable: false,
+			gimbalRollRotateAngle: degrees(0),
+			gimbalYawRotateEnable: false,
+			gimbalYawRotateAngle: degrees(0),
+			gimbalRotateTimeEnable: false,
+			gimbalRotateTime: 10
+		}
+	};
+}
+function pathPoints(template, lineSpacingM, preferredStartPoint) {
+	const placemark = template.Folder.Placemark;
+	const ring = parseCoordinatesString(placemark.Polygon.outerBoundaryIs.LinearRing.coordinates);
+	if (ring.length < 3) throw new PlannerError("targetdetection requires at least 3 polygon vertices");
+	const centerLat = ring.reduce((sum, point) => sum + point.lat, 0) / ring.length;
+	const scale = 1 / Math.cos(centerLat * DEG2RAD);
+	const theta = Number(placemark.direction) * DEG2RAD;
+	const u = [Math.sin(theta), Math.cos(theta)];
+	const n = [-Math.cos(theta), Math.sin(theta)];
+	const height = Number(placemark.height);
+	const pitch = Math.abs(Number(placemark.gimbalPitchAngle));
+	const lookAheadM = pitch >= 89.999999 ? 0 : height / Math.tan(pitch * DEG2RAD);
+	const scanRing = offsetPolygon(ring.map((point) => {
+		const [x, y] = project(point);
+		return [x - u[0] * lookAheadM * scale, y - u[1] * lookAheadM * scale];
+	}), placemark.margin * scale).map(([x, y]) => [x * u[0] + y * u[1], x * n[0] + y * n[1]]);
+	const cross = scanRing.map((point) => point[1]);
+	const min = Math.min(...cross);
+	const max = Math.max(...cross);
+	const spacing = lineSpacingM * scale;
+	const stripCount = Math.max(1, Math.floor((max - min) / spacing));
+	const center = (min + max) / 2;
+	const segments = [];
+	for (let i = 0; i < stripCount; i++) {
+		const q = center + (i - (stripCount - 1) / 2) * spacing;
+		for (const [a, b] of clipHorizontal(q, scanRing)) segments.push([[u[0] * a + n[0] * q, u[1] * a + n[1] * q], [u[0] * b + n[0] * q, u[1] * b + n[1] * q]]);
+	}
+	let points = segments.flatMap(([a, b], index) => index % 2 === 0 ? [a, b] : [b, a]);
+	if (preferredStartPoint && points.length > 1) {
+		const preferred = project(preferredStartPoint);
+		const distance2 = ([x, y]) => (x - preferred[0]) ** 2 + (y - preferred[1]) ** 2;
+		if (distance2(points.at(-1)) < distance2(points[0])) points = points.reverse();
+	}
+	return points.map(unproject);
+}
+function turnDamping(points, index) {
+	if (index === 0 || index === points.length - 1) return meters(0);
+	const groundDistance = (a, b) => {
+		const [ax, ay] = project(a);
+		const [bx, by] = project(b);
+		return Math.hypot(bx - ax, by - ay) * Math.cos((a.lat + b.lat) / 2 * DEG2RAD);
+	};
+	return meters(Math.min(10, groundDistance(points[index - 1], points[index]) / 3, groundDistance(points[index], points[index + 1]) / 3));
+}
+function planTargetDetection(template, options) {
+	const spacing = Number(options?.lineSpacing);
+	if (!(spacing > 0 && Number.isFinite(spacing))) throw new PlannerError("targetdetection requires options.lineSpacing");
+	const folder = template.Folder;
+	const pitch = Number(folder.Placemark.gimbalPitchAngle);
+	const direction = Number(folder.Placemark.direction);
+	const points = pathPoints(template, spacing, options?.preferredStartPoint);
+	if (points.length < 2) throw new PlannerError("targetdetection polygon produced no flight path");
+	const lastIndex = points.length - 1;
+	const action = gimbalAction(pitch);
+	const placemarks = points.map((point, index) => ({
+		Point: { coordinates: point },
+		index,
+		executeHeight: folder.waylineCoordinateSysParam.heightMode === "aboveGroundLevel" ? options?.resolveExecuteHeight?.({
+			...point,
+			index,
+			waylineId: 0
+		}) ?? folder.Placemark.height : folder.Placemark.height,
+		waypointSpeed: folder.autoFlightSpeed,
+		waypointHeadingParam: index === lastIndex ? {
+			waypointHeadingMode: "followWayline",
+			waypointHeadingPathMode: "followBadArc"
+		} : {
+			waypointHeadingMode: "fixed",
+			waypointHeadingAngle: degrees(direction),
+			waypointHeadingAngleEnable: true,
+			waypointHeadingPathMode: "followBadArc",
+			waypointHeadingPoiIndex: 0
+		},
+		waypointTurnParam: index === 0 || index === lastIndex ? {
+			waypointTurnMode: "toPointAndStopWithDiscontinuityCurvature",
+			waypointTurnDampingDist: meters(0)
+		} : {
+			waypointTurnMode: "coordinateTurn",
+			waypointTurnDampingDist: turnDamping(points, index)
+		},
+		useStraightLine: true,
+		isRisky: false,
+		waypointWorkType: 0,
+		...index === 0 ? { actionGroup: [{
+			actionGroupId: 0,
+			actionGroupStartIndex: 0,
+			actionGroupEndIndex: lastIndex,
+			actionGroupMode: "sequence",
+			actionTrigger: { actionTriggerType: "betweenAdjacentPointsIncludeFirstPoint" },
+			action: [action]
+		}] } : {}
+	}));
+	return {
+		missionConfig: template.missionConfig,
+		Folder: [{
+			templateId: folder.templateId,
+			waylineId: 0,
+			executeHeightMode: executeHeightMode(folder),
+			autoFlightSpeed: folder.autoFlightSpeed,
+			startActionGroup: { action: [gimbalAction(pitch)] },
+			Placemark: placemarks
+		}]
+	};
+}
+//#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";
+const isTargetDetection = (t) => t.Folder.templateType === "targetdetection";
 /**
 * Compile a high-level `Template` into executable `Waylines`.
 * Dispatch is by `template.Folder.templateType` per the DJI WPML spec.
@@ -1842,6 +1988,7 @@ function plan(template, options) {
 	if (isMapping2d(template)) return planMapping2d(template, options);
 	if (isMapping3d(template)) return planMapping3d(template, options);
 	if (isMappingStrip(template)) return planMappingStrip(template, options);
+	if (isTargetDetection(template)) return planTargetDetection(template, options);
 	throw new PlannerError(`Unknown templateType: ${template.Folder.templateType}`);
 }
 //#endregion
@@ -1904,6 +2051,9 @@ function validateTemplate(template) {
 		case "mappingStrip":
 			issues.push(...validateMappingStripFolder(template, path));
 			break;
+		case "targetdetection":
+			issues.push(...validateTargetDetectionFolder(template, path));
+			break;
 	}
 	return issues;
 }
@@ -1922,6 +2072,9 @@ function validateMapping2dFolder(t, path) {
 function validateMapping3dFolder(t, path) {
 	return validatePolygonRing(t.Folder.Placemark.Polygon.outerBoundaryIs.LinearRing.coordinates, `${path}.Placemark.Polygon`);
 }
+function validateTargetDetectionFolder(t, path) {
+	return validatePolygonRing(t.Folder.Placemark.Polygon.outerBoundaryIs.LinearRing.coordinates, `${path}.Placemark.Polygon`);
+}
 function validateMappingStripFolder(t, path) {
 	const placemark = t.Folder.Placemark;
 	const tuples = placemark.LineString.coordinates.trim().split(/\s+/).filter(Boolean);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumikmz/kmz",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "DJI KMZ/WPML domain model + plan() algorithm + validate(), spec-aligned types mirroring docs/kmz/",
   "license": "MIT",
   "type": "module",

package/src/plan/geometry.ts

@@ -70,7 +70,7 @@ export function haversineMeters(a: LngLat, b: LngLat): number {
 }
 
 /** Clip a horizontal scan line `y = const` against a polygon; returns `[x_enter, x_exit]` pairs. */
-function clipHorizontal(y: number, polygon: readonly EnuPoint[]): [number, number][] {
+export function clipHorizontal(y: number, polygon: readonly EnuPoint[]): [number, number][] {
   const intersections: number[] = [];
   const n = polygon.length;
   for (let i = 0; i < n; i++) {

package/src/plan/index.ts

@@ -4,6 +4,7 @@ import type {
   Mapping2dTemplate,
   Mapping3dTemplate,
   MappingStripTemplate,
+  TargetDetectionTemplate,
   Template,
   WaypointTemplate,
 } from "../types/template.js";
@@ -12,6 +13,8 @@ import { planMapping2d } from "./plan-mapping2d.js";
 import { planMapping3d } from "./plan-mapping3d.js";
 import { planMappingStrip } from "./plan-mapping-strip.js";
 import { planWaypoint } from "./plan-waypoint.js";
+import { planTargetDetection } from "./plan-target-detection.js";
+import type { LngLat } from "../types/branded.js";
 
 /**
  * Options for `plan()`.
@@ -34,6 +37,8 @@ export interface PlanOptions {
   stripDirection?: "parallel" | "perpendicular";
   /** Reverse mappingStrip region execution without changing region identities. */
   regionOrderReversed?: boolean;
+  /** Preferred entry location for path variants that can be reversed as a whole. */
+  preferredStartPoint?: LngLat;
   resolveExecuteHeight?: (point: {
     lng: number;
     lat: number;
@@ -47,6 +52,8 @@ const isMapping2d = (t: Template): t is Mapping2dTemplate => t.Folder.templateTy
 const isMapping3d = (t: Template): t is Mapping3dTemplate => t.Folder.templateType === "mapping3d";
 const isMappingStrip = (t: Template): t is MappingStripTemplate =>
   t.Folder.templateType === "mappingStrip";
+const isTargetDetection = (t: Template): t is TargetDetectionTemplate =>
+  t.Folder.templateType === "targetdetection";
 
 /**
  * Compile a high-level `Template` into executable `Waylines`.
@@ -59,5 +66,6 @@ export function plan(template: Template, options?: PlanOptions): Waylines {
   if (isMapping2d(template)) return planMapping2d(template, options);
   if (isMapping3d(template)) return planMapping3d(template, options);
   if (isMappingStrip(template)) return planMappingStrip(template, options);
+  if (isTargetDetection(template)) return planTargetDetection(template, options);
   throw new PlannerError(`Unknown templateType: ${(template as Template).Folder.templateType}`);
 }

package/src/plan/plan-target-detection.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { degrees, meters, metersPerSecond } from "../types/branded.js";
+import type { TargetDetectionTemplate } from "../types/template.js";
+import { plan } from "./index.js";
+
+function template(overrides: { pitch?: number; direction?: number } = {}): TargetDetectionTemplate {
+  const pitch = overrides.pitch ?? -90;
+  const direction = overrides.direction ?? 0;
+  return {
+    missionConfig: {
+      flyToWaylineMode: "safely",
+      finishAction: "goHome",
+      exitOnRCLost: "goContinue",
+      takeOffSecurityHeight: meters(20),
+      globalTransitionalSpeed: metersPerSecond(15),
+      globalRTHHeight: meters(100),
+      droneInfo: { droneEnumValue: 100, droneSubEnumValue: 1 },
+      payloadInfo: [{ payloadEnumValue: 99, payloadSubEnumValue: 2, payloadPositionIndex: 0 }],
+    },
+    Folder: {
+      templateType: "targetdetection",
+      templateId: 0,
+      waylineCoordinateSysParam: {
+        coordinateMode: "WGS84",
+        heightMode: "relativeToStartPoint",
+        globalShootHeight: meters(60),
+        surfaceFollowModeEnable: false,
+      },
+      autoFlightSpeed: metersPerSecond(10),
+      payloadParam: { payloadPositionIndex: 0, imageFormat: ["ir"] },
+      Placemark: {
+        direction: degrees(direction),
+        margin: 0,
+        gimbalPitchMode: "fixed",
+        overlap: { orthoCameraOverlapH: 1, orthoCameraOverlapW: 20 },
+        Polygon: {
+          outerBoundaryIs: {
+            LinearRing: {
+              coordinates: "0,0,0 0.001,0,0 0.001,0.002,0 0,0.002,0",
+            },
+          },
+        },
+        ellipsoidHeight: meters(60),
+        height: meters(60),
+        mappingHeadingParam: {
+          mappingHeadingMode: "fixed",
+          mappingHeadingAngle: degrees(direction),
+        },
+        gimbalPitchAngle: degrees(pitch),
+        recordEnable: false,
+      },
+    },
+  };
+}
+
+describe("plan(targetdetection)", () => {
+  it("centers floor(width / spacing) scan lines", () => {
+    const waylines = plan(template(), { lineSpacing: meters(25) });
+
+    expect(waylines.Folder).toHaveLength(1);
+    expect(waylines.Folder[0]!.Placemark).toHaveLength(8);
+  });
+
+  it("shifts the flight path backward by height / tan(abs(pitch))", () => {
+    const placemarks = plan(template({ pitch: -45 }), {
+      lineSpacing: meters(25),
+    }).Folder[0]!.Placemark;
+    const centerLat =
+      placemarks.reduce((sum, point) => sum + point.Point.coordinates.lat, 0) / placemarks.length;
+
+    expect(centerLat).toBeCloseTo(0.000461, 5);
+  });
+
+  it("retains every clipped segment of a concave polygon", () => {
+    const concave = template({ direction: 90 });
+    concave.Folder.Placemark.Polygon.outerBoundaryIs.LinearRing.coordinates =
+      "0,0,0 0.003,0,0 0.003,0.003,0 0.002,0.003,0 0.002,0.001,0 0.001,0.001,0 0.001,0.003,0 0,0.003,0";
+
+    const placemarks = plan(concave, { lineSpacing: meters(100) }).Folder[0]!.Placemark;
+
+    expect(placemarks).toHaveLength(10);
+  });
+
+  it("keeps fixed heading and pitch with one-third turn damping", () => {
+    const placemarks = plan(template({ pitch: -45, direction: 0 }), {
+      lineSpacing: meters(25),
+    }).Folder[0]!.Placemark;
+
+    expect(
+      placemarks.slice(0, -1).every((p) => p.waypointHeadingParam.waypointHeadingMode === "fixed"),
+    ).toBe(true);
+    expect(placemarks[0]!.actionGroup?.[0]!.action[0]).toMatchObject({
+      actionActuatorFunc: "gimbalRotate",
+      actionActuatorFuncParam: { gimbalPitchRotateAngle: -45 },
+    });
+    expect(Number(placemarks[1]!.waypointTurnParam.waypointTurnDampingDist)).toBeCloseTo(25 / 3, 5);
+    expect(Number(placemarks[0]!.waypointTurnParam.waypointTurnDampingDist)).toBe(0);
+    expect(Number(placemarks.at(-1)!.waypointTurnParam.waypointTurnDampingDist)).toBe(0);
+  });
+});

package/src/plan/plan-target-detection.ts

@@ -0,0 +1,208 @@
+import { degrees, meters, type LngLat, type Meters } from "../types/branded.js";
+import { PlannerError } from "../types/errors.js";
+import type { ExecuteHeightMode } from "../types/enums.js";
+import type { WaylinesPlacemark } from "../types/placemark.js";
+import type { TargetDetectionFolder, TargetDetectionTemplate } from "../types/template.js";
+import type { Waylines } from "../types/waylines.js";
+import { clipHorizontal, offsetPolygon, parseCoordinatesString } from "./geometry.js";
+import type { PlanOptions } from "./index.js";
+
+const EARTH_RADIUS_M = 6_378_137;
+const DEG2RAD = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+
+type Point = readonly [number, number];
+
+function project({ lng, lat }: LngLat): Point {
+  return [
+    EARTH_RADIUS_M * lng * DEG2RAD,
+    EARTH_RADIUS_M * Math.log(Math.tan(Math.PI / 4 + (lat * DEG2RAD) / 2)),
+  ];
+}
+
+function unproject([x, y]: Point): LngLat {
+  return {
+    lng: (x / EARTH_RADIUS_M) * RAD2DEG,
+    lat: (2 * Math.atan(Math.exp(y / EARTH_RADIUS_M)) - Math.PI / 2) * RAD2DEG,
+  };
+}
+
+function executeHeightMode(folder: TargetDetectionFolder): ExecuteHeightMode {
+  switch (folder.waylineCoordinateSysParam.heightMode) {
+    case "EGM96":
+      return "WGS84";
+    case "relativeToStartPoint":
+      return "relativeToStartPoint";
+    case "aboveGroundLevel":
+    case "realTimeFollowSurface":
+      return "realTimeFollowSurface";
+  }
+}
+
+function gimbalAction(pitch: number) {
+  return {
+    actionId: 0,
+    actionActuatorFunc: "gimbalRotate" as const,
+    actionActuatorFuncParam: {
+      payloadPositionIndex: 0,
+      gimbalHeadingYawBase: "aircraft" as const,
+      gimbalRotateMode: "absoluteAngle" as const,
+      gimbalPitchRotateEnable: true,
+      gimbalPitchRotateAngle: degrees(pitch),
+      gimbalRollRotateEnable: false,
+      gimbalRollRotateAngle: degrees(0),
+      gimbalYawRotateEnable: false,
+      gimbalYawRotateAngle: degrees(0),
+      gimbalRotateTimeEnable: false,
+      gimbalRotateTime: 10,
+    },
+  };
+}
+
+function pathPoints(
+  template: TargetDetectionTemplate,
+  lineSpacingM: number,
+  preferredStartPoint?: LngLat,
+): LngLat[] {
+  const placemark = template.Folder.Placemark;
+  const ring = parseCoordinatesString(placemark.Polygon.outerBoundaryIs.LinearRing.coordinates);
+  if (ring.length < 3)
+    throw new PlannerError("targetdetection requires at least 3 polygon vertices");
+
+  const centerLat = ring.reduce((sum, point) => sum + point.lat, 0) / ring.length;
+  const scale = 1 / Math.cos(centerLat * DEG2RAD);
+  const theta = Number(placemark.direction) * DEG2RAD;
+  const u: Point = [Math.sin(theta), Math.cos(theta)];
+  const n: Point = [-Math.cos(theta), Math.sin(theta)];
+  const height = Number(placemark.height);
+  const pitch = Math.abs(Number(placemark.gimbalPitchAngle));
+  const lookAheadM = pitch >= 89.999999 ? 0 : height / Math.tan(pitch * DEG2RAD);
+
+  const translated = ring.map((point) => {
+    const [x, y] = project(point);
+    return [x - u[0] * lookAheadM * scale, y - u[1] * lookAheadM * scale] as Point;
+  });
+  const flightRing = offsetPolygon(translated, placemark.margin * scale);
+  const scanRing = flightRing.map(([x, y]) => [x * u[0] + y * u[1], x * n[0] + y * n[1]] as Point);
+  const cross = scanRing.map((point) => point[1]);
+  const min = Math.min(...cross);
+  const max = Math.max(...cross);
+  const spacing = lineSpacingM * scale;
+  const stripCount = Math.max(1, Math.floor((max - min) / spacing));
+  const center = (min + max) / 2;
+
+  const segments: [Point, Point][] = [];
+  for (let i = 0; i < stripCount; i++) {
+    const q = center + (i - (stripCount - 1) / 2) * spacing;
+    for (const [a, b] of clipHorizontal(q, scanRing)) {
+      segments.push([
+        [u[0] * a + n[0] * q, u[1] * a + n[1] * q],
+        [u[0] * b + n[0] * q, u[1] * b + n[1] * q],
+      ]);
+    }
+  }
+
+  let points = segments.flatMap(([a, b], index) => (index % 2 === 0 ? [a, b] : [b, a]));
+  if (preferredStartPoint && points.length > 1) {
+    const preferred = project(preferredStartPoint);
+    const distance2 = ([x, y]: Point) => (x - preferred[0]) ** 2 + (y - preferred[1]) ** 2;
+    if (distance2(points.at(-1)!) < distance2(points[0]!)) points = points.reverse();
+  }
+  return points.map(unproject);
+}
+
+function turnDamping(points: readonly LngLat[], index: number): Meters {
+  if (index === 0 || index === points.length - 1) return meters(0);
+  const groundDistance = (a: LngLat, b: LngLat) => {
+    const [ax, ay] = project(a);
+    const [bx, by] = project(b);
+    return Math.hypot(bx - ax, by - ay) * Math.cos(((a.lat + b.lat) / 2) * DEG2RAD);
+  };
+  return meters(
+    Math.min(
+      10,
+      groundDistance(points[index - 1]!, points[index]!) / 3,
+      groundDistance(points[index]!, points[index + 1]!) / 3,
+    ),
+  );
+}
+
+export function planTargetDetection(
+  template: TargetDetectionTemplate,
+  options?: PlanOptions,
+): Waylines {
+  const spacing = Number(options?.lineSpacing);
+  if (!(spacing > 0 && Number.isFinite(spacing))) {
+    throw new PlannerError("targetdetection requires options.lineSpacing");
+  }
+
+  const folder = template.Folder;
+  const pitch = Number(folder.Placemark.gimbalPitchAngle);
+  const direction = Number(folder.Placemark.direction);
+  const points = pathPoints(template, spacing, options?.preferredStartPoint);
+  if (points.length < 2) throw new PlannerError("targetdetection polygon produced no flight path");
+  const lastIndex = points.length - 1;
+  const action = gimbalAction(pitch);
+
+  const placemarks: WaylinesPlacemark[] = points.map((point, index) => ({
+    Point: { coordinates: point },
+    index,
+    executeHeight:
+      folder.waylineCoordinateSysParam.heightMode === "aboveGroundLevel"
+        ? (options?.resolveExecuteHeight?.({ ...point, index, waylineId: 0 }) ??
+          folder.Placemark.height)
+        : folder.Placemark.height,
+    waypointSpeed: folder.autoFlightSpeed,
+    waypointHeadingParam:
+      index === lastIndex
+        ? { waypointHeadingMode: "followWayline", waypointHeadingPathMode: "followBadArc" }
+        : {
+            waypointHeadingMode: "fixed",
+            waypointHeadingAngle: degrees(direction),
+            waypointHeadingAngleEnable: true,
+            waypointHeadingPathMode: "followBadArc",
+            waypointHeadingPoiIndex: 0,
+          },
+    waypointTurnParam:
+      index === 0 || index === lastIndex
+        ? {
+            waypointTurnMode: "toPointAndStopWithDiscontinuityCurvature",
+            waypointTurnDampingDist: meters(0),
+          }
+        : {
+            waypointTurnMode: "coordinateTurn",
+            waypointTurnDampingDist: turnDamping(points, index),
+          },
+    useStraightLine: true,
+    isRisky: false,
+    waypointWorkType: 0,
+    ...(index === 0
+      ? {
+          actionGroup: [
+            {
+              actionGroupId: 0,
+              actionGroupStartIndex: 0,
+              actionGroupEndIndex: lastIndex,
+              actionGroupMode: "sequence",
+              actionTrigger: { actionTriggerType: "betweenAdjacentPointsIncludeFirstPoint" },
+              action: [action],
+            },
+          ],
+        }
+      : {}),
+  }));
+
+  return {
+    missionConfig: template.missionConfig,
+    Folder: [
+      {
+        templateId: folder.templateId,
+        waylineId: 0,
+        executeHeightMode: executeHeightMode(folder),
+        autoFlightSpeed: folder.autoFlightSpeed,
+        startActionGroup: { action: [gimbalAction(pitch)] },
+        Placemark: placemarks,
+      },
+    ],
+  };
+}

package/src/types/enums.ts

@@ -8,7 +8,12 @@ export type ExitOnRCLost = "goContinue" | "executeLostAction";
 
 export type ExecuteRCLostAction = "goBack" | "landing" | "hover";
 
-export type TemplateType = "waypoint" | "mapping2d" | "mapping3d" | "mappingStrip";
+export type TemplateType =
+  | "waypoint"
+  | "mapping2d"
+  | "mapping3d"
+  | "mappingStrip"
+  | "targetdetection";
 
 export type CoordinateMode = "WGS84";
 
@@ -63,6 +68,7 @@ export type ActionGroupMode = "sequence";
 export type ActionTriggerType =
   | "reachPoint"
   | "betweenAdjacentPoints"
+  | "betweenAdjacentPointsIncludeFirstPoint"
   | "multipleTiming"
   | "multipleDistance";
 

package/src/types/mission-config.ts

@@ -31,6 +31,8 @@ export interface MissionConfig {
   globalRTHHeight: Meters;
   droneInfo: DroneInfo;
   payloadInfo: PayloadInfo[];
+  /** FlightHub 2 custom restricted-area avoidance switch. */
+  waylineAvoidLimitAreaMode?: boolean;
   /** Only M3D/M3TD, M4D/M4TD, M4E/M4T. */
   autoRerouteInfo?: AutoRerouteInfo;
 }

package/src/types/placemark.ts

@@ -115,6 +115,20 @@ export interface Mapping3dPlacemark {
   height: Meters;
 }
 
+/** `Placemark` inside a FlightHub 2 patrol-area `targetdetection` Folder. */
+export interface TargetDetectionPlacemark {
+  direction: Degrees;
+  margin: number;
+  gimbalPitchMode: "fixed";
+  overlap: Overlap;
+  Polygon: TemplatePolygon;
+  ellipsoidHeight: Meters;
+  height: Meters;
+  mappingHeadingParam: MappingHeadingParam;
+  gimbalPitchAngle: Degrees;
+  recordEnable: boolean;
+}
+
 /** `Placemark` inside a `mappingStrip` Folder — uses a LineString; params live here. */
 export interface MappingStripPlacemark {
   caliFlightEnable: boolean;

package/src/types/template.ts

@@ -6,6 +6,7 @@ import type {
   Mapping2dPlacemark,
   Mapping3dPlacemark,
   MappingStripPlacemark,
+  TargetDetectionPlacemark,
   TemplateWaypointPlacemark,
 } from "./placemark.js";
 
@@ -17,7 +18,8 @@ export type Template =
   | WaypointTemplate
   | Mapping2dTemplate
   | Mapping3dTemplate
-  | MappingStripTemplate;
+  | MappingStripTemplate
+  | TargetDetectionTemplate;
 
 interface TemplateDocumentBase {
   /** Unix milliseconds. */
@@ -93,6 +95,21 @@ export interface Mapping3dFolder {
   Placemark: Mapping3dPlacemark;
 }
 
+// ─── targetdetection (patrol area) ──────────────────────────────────────────
+
+export interface TargetDetectionTemplate extends TemplateDocumentBase {
+  Folder: TargetDetectionFolder;
+}
+
+export interface TargetDetectionFolder {
+  templateType: "targetdetection";
+  templateId: number;
+  waylineCoordinateSysParam: WaylineCoordinateSysParam;
+  autoFlightSpeed: MetersPerSecond;
+  payloadParam?: PayloadParam;
+  Placemark: TargetDetectionPlacemark;
+}
+
 // ─── mappingStrip ────────────────────────────────────────────────────────────
 
 export interface MappingStripTemplate extends TemplateDocumentBase {

package/src/validate/validate-template.ts

@@ -3,6 +3,7 @@ import type {
   Mapping2dTemplate,
   Mapping3dTemplate,
   MappingStripTemplate,
+  TargetDetectionTemplate,
   Template,
   WaypointTemplate,
 } from "../types/template.js";
@@ -41,6 +42,9 @@ export function validateTemplate(template: Template): Issue[] {
     case "mappingStrip":
       issues.push(...validateMappingStripFolder(template as MappingStripTemplate, path));
       break;
+    case "targetdetection":
+      issues.push(...validateTargetDetectionFolder(template as TargetDetectionTemplate, path));
+      break;
   }
 
   return issues;
@@ -72,6 +76,13 @@ function validateMapping3dFolder(t: Mapping3dTemplate, path: string): Issue[] {
   );
 }
 
+function validateTargetDetectionFolder(t: TargetDetectionTemplate, path: string): Issue[] {
+  return validatePolygonRing(
+    t.Folder.Placemark.Polygon.outerBoundaryIs.LinearRing.coordinates,
+    `${path}.Placemark.Polygon`,
+  );
+}
+
 function validateMappingStripFolder(t: MappingStripTemplate, path: string): Issue[] {
   const placemark = t.Folder.Placemark;
   const tuples = placemark.LineString.coordinates.trim().split(/\s+/).filter(Boolean);