@lumikmz/kmz 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -59,7 +59,7 @@ type LidarReturnMode = "singleReturnStrongest" | "dualReturn" | "tripleReturn";
 type LidarScanningMode = "repetitive" | "nonRepetitive";
 type ActionGroupMode = "sequence";
 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 ActionActuatorFunc = "targetDetection" | "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";
 type AircraftPathMode = "clockwise" | "counterClockwise";
@@ -81,6 +81,8 @@ interface PayloadInfo {
    */
   payloadSubEnumValue?: number;
   payloadPositionIndex: number;
+  /** FlightHub 2 patrol-camera selection, in 35mm-equivalent millimeters. */
+  equivalentFocalLength?: number;
 }
 /** Aircraft `{ droneEnumValue, droneSubEnumValue }` tuples. */
 declare const DroneEnum: {
@@ -399,12 +401,36 @@ interface ActionTrigger {
   actionTriggerParam?: number;
 }
 /** Discriminated by `actionActuatorFunc`. */
-type Action = TakePhotoAction | StartRecordAction | StopRecordAction | FocusAction | ZoomAction | CustomDirNameAction | GimbalRotateAction | RotateYawAction | HoverAction | GimbalEvenlyRotateAction | AccurateShootAction | OrientedShootAction | PanoShotAction | RecordPointCloudAction | MegaphoneAction | SearchlightAction | StartSmartObliqueAction | StopSmartObliqueAction | StartTimeLapseAction | StopTimeLapseAction | GimbalAngleLockAction | GimbalAngleUnlockAction | SetFocusTypeAction;
+type Action = TargetDetectionAction | TakePhotoAction | StartRecordAction | StopRecordAction | FocusAction | ZoomAction | CustomDirNameAction | GimbalRotateAction | RotateYawAction | HoverAction | GimbalEvenlyRotateAction | AccurateShootAction | OrientedShootAction | PanoShotAction | RecordPointCloudAction | MegaphoneAction | SearchlightAction | StartSmartObliqueAction | StopSmartObliqueAction | StartTimeLapseAction | StopTimeLapseAction | GimbalAngleLockAction | GimbalAngleUnlockAction | SetFocusTypeAction;
 interface ActionBase<F extends string, P> {
   actionId: number;
   actionActuatorFunc: F;
   actionActuatorFuncParam: P;
 }
+interface TargetDetectionParam {
+  focalLength?: number;
+  payloadPositionIndex: number;
+  useGlobalPayloadLensIndex: boolean;
+  payloadLensIndex: LensType[];
+  actionUUID: string;
+  irGainMode?: string;
+  irColorPalette?: string;
+  customTitle: string;
+  customText: string;
+  modelIndex: number;
+  modelScore: number;
+  alarmInterval: number;
+  useThirdModel: boolean;
+  algorithmType: string;
+  targetParam: {
+    maxThreshold: number;
+    minThreshold: number;
+    useMaxThreshold: boolean;
+    useMinThreshold: boolean;
+    targetType: string;
+  };
+}
+type TargetDetectionAction = ActionBase<"targetDetection", TargetDetectionParam>;
 interface TakePhotoParam {
   payloadPositionIndex: number;
   fileSuffix?: string;
@@ -763,6 +789,9 @@ interface TargetDetectionPlacemark {
   mappingHeadingParam: MappingHeadingParam;
   gimbalPitchAngle: Degrees;
   recordEnable: boolean;
+  /** FlightHub 2 always emits this action for patrol-area routes. */
+  targetDetectionActionEnable?: boolean;
+  action?: TargetDetectionAction;
 }
 /** `Placemark` inside a `mappingStrip` Folder — uses a LineString; params live here. */
 interface MappingStripPlacemark {
@@ -1031,4 +1060,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, 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 };
+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, TargetDetectionAction, TargetDetectionFolder, TargetDetectionParam, 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

@@ -1866,6 +1866,17 @@ function gimbalAction(pitch) {
 		}
 	};
 }
+function startRecordAction(payloadPositionIndex, actionId) {
+	return {
+		actionId,
+		actionActuatorFunc: "startRecord",
+		actionActuatorFuncParam: {
+			payloadPositionIndex,
+			useGlobalPayloadLensIndex: true,
+			payloadLensIndex: ["visable"]
+		}
+	};
+}
 function pathPoints(template, lineSpacingM, preferredStartPoint) {
 	const placemark = template.Folder.Placemark;
 	const ring = parseCoordinatesString(placemark.Polygon.outerBoundaryIs.LinearRing.coordinates);
@@ -1920,6 +1931,13 @@ function planTargetDetection(template, options) {
 	if (points.length < 2) throw new PlannerError("targetdetection polygon produced no flight path");
 	const lastIndex = points.length - 1;
 	const action = gimbalAction(pitch);
+	const payloadPositionIndex = folder.payloadParam?.payloadPositionIndex ?? 0;
+	const routeActions = [action];
+	if (folder.Placemark.recordEnable) routeActions.push(startRecordAction(payloadPositionIndex, routeActions.length));
+	if (folder.Placemark.action) routeActions.push({
+		...folder.Placemark.action,
+		actionId: routeActions.length
+	});
 	const placemarks = points.map((point, index) => ({
 		Point: { coordinates: point },
 		index,
@@ -1955,7 +1973,7 @@ function planTargetDetection(template, options) {
 			actionGroupEndIndex: lastIndex,
 			actionGroupMode: "sequence",
 			actionTrigger: { actionTriggerType: "betweenAdjacentPointsIncludeFirstPoint" },
-			action: [action]
+			action: routeActions
 		}] } : {}
 	}));
 	return {
@@ -1965,7 +1983,7 @@ function planTargetDetection(template, options) {
 			waylineId: 0,
 			executeHeightMode: executeHeightMode(folder),
 			autoFlightSpeed: folder.autoFlightSpeed,
-			startActionGroup: { action: [gimbalAction(pitch)] },
+			startActionGroup: { action: folder.Placemark.recordEnable ? [gimbalAction(pitch), startRecordAction(payloadPositionIndex, 1)] : [gimbalAction(pitch)] },
 			Placemark: placemarks
 		}]
 	};

package/package.json

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

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

@@ -54,6 +54,49 @@ function template(overrides: { pitch?: number; direction?: number } = {}): Targe
 }
 
 describe("plan(targetdetection)", () => {
+  it("matches FlightHub recording and target-detection actions without stopRecord", () => {
+    const input = template();
+    Object.assign(input.Folder.Placemark, {
+      recordEnable: true,
+      targetDetectionActionEnable: true,
+      action: {
+        actionId: 0,
+        actionActuatorFunc: "targetDetection",
+        actionActuatorFuncParam: {
+          focalLength: 70,
+          payloadPositionIndex: 0,
+          useGlobalPayloadLensIndex: false,
+          payloadLensIndex: ["visable"],
+          actionUUID: "test-target-detection",
+          customTitle: "巡逻",
+          customText: "检测到异常目标",
+          modelIndex: 0,
+          modelScore: 55,
+          alarmInterval: 2,
+          useThirdModel: false,
+          algorithmType: "visable_ai",
+          targetParam: {
+            maxThreshold: 10,
+            minThreshold: 10,
+            useMaxThreshold: false,
+            useMinThreshold: true,
+            targetType: "person",
+          },
+        },
+      },
+    });
+
+    const folder = plan(input, { lineSpacing: meters(25) }).Folder[0]!;
+    const startFuncs = folder.startActionGroup!.action.map((a) => a.actionActuatorFunc);
+    const routeFuncs = folder.Placemark[0]!.actionGroup![0]!.action.map(
+      (a) => a.actionActuatorFunc,
+    );
+
+    expect(startFuncs).toEqual(["gimbalRotate", "startRecord"]);
+    expect(routeFuncs).toEqual(["gimbalRotate", "startRecord", "targetDetection"]);
+    expect(JSON.stringify(folder)).not.toContain("stopRecord");
+  });
+
   it("centers floor(width / spacing) scan lines", () => {
     const waylines = plan(template(), { lineSpacing: meters(25) });
 

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

@@ -1,4 +1,5 @@
 import { degrees, meters, type LngLat, type Meters } from "../types/branded.js";
+import type { Action } from "../types/action.js";
 import { PlannerError } from "../types/errors.js";
 import type { ExecuteHeightMode } from "../types/enums.js";
 import type { WaylinesPlacemark } from "../types/placemark.js";
@@ -59,6 +60,18 @@ function gimbalAction(pitch: number) {
   };
 }
 
+function startRecordAction(payloadPositionIndex: number, actionId: number) {
+  return {
+    actionId,
+    actionActuatorFunc: "startRecord" as const,
+    actionActuatorFuncParam: {
+      payloadPositionIndex,
+      useGlobalPayloadLensIndex: true,
+      payloadLensIndex: ["visable" as const],
+    },
+  };
+}
+
 function pathPoints(
   template: TargetDetectionTemplate,
   lineSpacingM: number,
@@ -143,6 +156,14 @@ export function planTargetDetection(
   if (points.length < 2) throw new PlannerError("targetdetection polygon produced no flight path");
   const lastIndex = points.length - 1;
   const action = gimbalAction(pitch);
+  const payloadPositionIndex = folder.payloadParam?.payloadPositionIndex ?? 0;
+  const routeActions: Action[] = [action];
+  if (folder.Placemark.recordEnable) {
+    routeActions.push(startRecordAction(payloadPositionIndex, routeActions.length));
+  }
+  if (folder.Placemark.action) {
+    routeActions.push({ ...folder.Placemark.action, actionId: routeActions.length });
+  }
 
   const placemarks: WaylinesPlacemark[] = points.map((point, index) => ({
     Point: { coordinates: point },
@@ -185,7 +206,7 @@ export function planTargetDetection(
               actionGroupEndIndex: lastIndex,
               actionGroupMode: "sequence",
               actionTrigger: { actionTriggerType: "betweenAdjacentPointsIncludeFirstPoint" },
-              action: [action],
+              action: routeActions,
             },
           ],
         }
@@ -200,7 +221,11 @@ export function planTargetDetection(
         waylineId: 0,
         executeHeightMode: executeHeightMode(folder),
         autoFlightSpeed: folder.autoFlightSpeed,
-        startActionGroup: { action: [gimbalAction(pitch)] },
+        startActionGroup: {
+          action: folder.Placemark.recordEnable
+            ? [gimbalAction(pitch), startRecordAction(payloadPositionIndex, 1)]
+            : [gimbalAction(pitch)],
+        },
         Placemark: placemarks,
       },
     ],

package/src/types/action.ts

@@ -34,6 +34,7 @@ export interface ActionTrigger {
 
 /** Discriminated by `actionActuatorFunc`. */
 export type Action =
+  | TargetDetectionAction
   | TakePhotoAction
   | StartRecordAction
   | StopRecordAction
@@ -64,6 +65,31 @@ interface ActionBase<F extends string, P> {
   actionActuatorFuncParam: P;
 }
 
+export interface TargetDetectionParam {
+  focalLength?: number;
+  payloadPositionIndex: number;
+  useGlobalPayloadLensIndex: boolean;
+  payloadLensIndex: LensType[];
+  actionUUID: string;
+  irGainMode?: string;
+  irColorPalette?: string;
+  customTitle: string;
+  customText: string;
+  modelIndex: number;
+  modelScore: number;
+  alarmInterval: number;
+  useThirdModel: boolean;
+  algorithmType: string;
+  targetParam: {
+    maxThreshold: number;
+    minThreshold: number;
+    useMaxThreshold: boolean;
+    useMinThreshold: boolean;
+    targetType: string;
+  };
+}
+export type TargetDetectionAction = ActionBase<"targetDetection", TargetDetectionParam>;
+
 // ─── Action params (one type per actionActuatorFunc) ─────────────────────────
 
 export interface TakePhotoParam {

package/src/types/drone-payload.ts

@@ -15,6 +15,8 @@ export interface PayloadInfo {
    */
   payloadSubEnumValue?: number;
   payloadPositionIndex: number;
+  /** FlightHub 2 patrol-camera selection, in 35mm-equivalent millimeters. */
+  equivalentFocalLength?: number;
 }
 
 /** Aircraft `{ droneEnumValue, droneSubEnumValue }` tuples. */

package/src/types/enums.ts

@@ -73,6 +73,7 @@ export type ActionTriggerType =
   | "multipleDistance";
 
 export type ActionActuatorFunc =
+  | "targetDetection"
   | "takePhoto"
   | "startRecord"
   | "stopRecord"

package/src/types/placemark.ts

@@ -1,5 +1,5 @@
 import type { Degrees, LngLat, Meters, MetersPerSecond } from "./branded.js";
-import type { ActionGroup } from "./action.js";
+import type { ActionGroup, TargetDetectionAction } from "./action.js";
 import type { ExecuteHeightMode, ShootType } from "./enums.js";
 import type {
   MappingHeadingParam,
@@ -127,6 +127,9 @@ export interface TargetDetectionPlacemark {
   mappingHeadingParam: MappingHeadingParam;
   gimbalPitchAngle: Degrees;
   recordEnable: boolean;
+  /** FlightHub 2 always emits this action for patrol-area routes. */
+  targetDetectionActionEnable?: boolean;
+  action?: TargetDetectionAction;
 }
 
 /** `Placemark` inside a `mappingStrip` Folder — uses a LineString; params live here. */