• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 智能拍摄跟踪开发指南
2<!--Kit: Mechanic Kit-->
3<!--Subsystem: Mechanic-->
4<!--Owner: @hobbycao-->
5<!--Designer: @saga2025-->
6<!--Tester: @zhaodengqi-->
7<!--Adviser: @foryourself-->
8
9从API version 20开始，支持使用机械设备管理。在视频录制和直播等应用场景中，开发者希望为拥有机械体配件设备的用户提供更丰富的拍摄体验，如人脸智能跟踪和自动构图等专业拍摄功能。
10
11智能拍摄跟踪，可以通过机械体配件设备实现人脸跟踪和物体追踪等自动化拍摄功能，提升拍摄质量和用户体验，帮助开发者构建出更智能、更高效的拍摄解决方案。
12
13## 接口介绍
14
15机械设备管理API的接口使用指导请参见[MechanicManager  API参考](../reference/apis-mechanic-kit/js-apis-mechanicManager.md)。
16
17| 接口名                                                               | 描述                       |
18| -------------------------------------------------------------------- | -------------------------- |
19|on(type: 'attachStateChange', callback: Callback\<AttachStateChangeInfo>): void | 注册attachStateChange事件的回调监听，等待连接状态变化。<br>**说明**：从API version 20开始支持。|
20|off(type: 'attachStateChange', callback?: Callback\<AttachStateChangeInfo>): void | 取消注册attachStateChange事件的回调监听。<br>**说明**：从API version 20开始支持。|
21|getAttachedMechDevices(): MechInfo[] | 获取已连接的机械体设备列表。<br>**说明**：从API version 20开始支持。|
22|setCameraTrackingEnabled(isEnabled: boolean): void | 启用或禁用摄像头跟踪。<br>**说明**：从API version 20开始支持。|
23|getCameraTrackingEnabled(): boolean | 检查是否启用了摄像头跟踪。<br>**说明**：从API version 20开始支持。|
24|on(type: 'trackingStateChange', callback: Callback\<TrackingEventInfo>): void | 注册trackingStateChange事件的回调监听。<br>**说明**：从API version 20开始支持。|
25|off(type: 'trackingStateChange', callback?: Callback\<TrackingEventInfo>): void | 取消注册trackingStateChange事件的回调监听。<br>**说明**：从API version 20开始支持。|
26|setCameraTrackingLayout(trackingLayout: CameraTrackingLayout): void | 设置摄像头跟踪布局。<br>**说明**：从API version 20开始支持。|
27|getCameraTrackingLayout(): CameraTrackingLayout | 获取此机械设备摄像头跟踪布局。<br>**说明**：从API version 20开始支持。|
28|on(type: 'rotationAxesStatusChange', callback: Callback\<RotationAxesStateChangeInfo>): void | 注册rotationAxesStatusChange事件的回调监听。<br>**说明**：从API version 20开始支持。|
29|off(type: 'rotationAxesStatusChange', callback?: Callback\<RotationAxesStateChangeInfo>): void | 取消注册rotationAxesStatusChange事件的回调监听。<br>**说明**：从API version 20开始支持。|
30
31## 开发步骤
32
33### 开发准备
34
351. 一台支持MechanicKit协议的机械体配件设备。
36
372. 机械体配件设备与开发设备完成蓝牙连接。
38
39### 管理设备连接状态
40
41动态管理设备连接状态，确保设备连接或断开时应用能及时响应。
42
431. 导入机械设备管理模块文件。
44
45    ```ts
46    import mechanicManager from '@kit.MechanicKit';
47    ```
48
492. 获取已连接的机械设备列表。
50
51    ```ts
52    let savedMechanicIds: number[] = [];
53
54    try {
55    const devices = mechanicManager.getAttachedMechDevices();
56    console.info('Connected devices:', devices);
57
58    devices.forEach(device => {
59        console.info(`Device ID: ${device.mechId}`);
60        console.info(`Device Name: ${device.mechName}`);
61        console.info(`Device Type: ${device.mechDeviceType}`);
62
63    //保存设备类型为GIMBAL_DEVICE的设备的MechId
64        if (device.mechDeviceType === mechanicManager.MechDeviceType.GIMBAL_DEVICE) {
65        savedMechanicIds.push(device.mechId);
66        console.info(`GIMBAL_TYPE device saved ID: ${device.mechId}`);
67        } else {
68        console.info(`Skip non-gimbal devices: ${device.mechId}`);
69        }
70    });
71
72    console.info('List of saved gimbal device IDs:', savedMechanicIds);
73    } catch (err) {
74    console.error('Error getting attached devices:', err);
75    }
76    ```
77
783. 监听设备连接状态变化。
79
80    ```ts
81    const attachStateChangeCallback = (info: mechanicManager.AttachStateChangeInfo) => {
82    if (info.state === mechanicManager.AttachState.ATTACHED) {
83        console.info('Device attached:', info.mechInfo);
84        // 处理设备连接逻辑
85        handleDeviceAttached(info.mechInfo);
86    } else if (info.state === mechanicManager.AttachState.DETACHED) {
87        console.info('Device detached:', info.mechInfo);
88        // 处理设备断开逻辑
89        handleDeviceDetached(info.mechInfo);
90    }
91    };
92
93    // 注册监听
94    mechanicManager.on('attachStateChange', attachStateChangeCallback);
95    ```
96
974. 处理设备连接和断开事件。
98
99    ```ts
100    function handleDeviceAttached(mechInfo: mechanicManager.MechInfo) {
101    console.info(`New device is connected: ${mechInfo.mechName} (ID: ${mechInfo.mechId})`);
102    savedMechanicIds.push(mechInfo.mechId);
103    // To do sth.
104    }
105
106    function handleDeviceDetached(mechInfo: mechanicManager.MechInfo) {
107    console.info(`Device disconnected: ${mechInfo.mechName} (ID: ${mechInfo.mechId})`);
108    savedMechanicIds.filter(id => id !== mechInfo.mechId);
109    // To do sth.
110    }
111    ```
112
1135. 取消监听。
114
115    ```ts
116    // 取消特定回调的监听
117    mechanicManager.off('attachStateChange', attachStateChangeCallback);
118    ```
119
120### 控制设备智能跟踪拍摄
121
122开启智能拍摄功能，机械体设备将自动识别人脸进行跟踪拍摄。
123
1241. 启用摄像头智能跟踪功能。
125
126    ```ts
127    try {
128    //检查前判断savedMechIds不为空
129    // 检查跟踪状态
130    const isEnabled = mechanicManager.getCameraTrackingEnabled();
131
132    if (isEnabled == false) {
133        // 开启摄像头跟踪
134        mechanicManager.setCameraTrackingEnabled(true);
135        console.info('Camera tracking enabled');
136    }
137
138    console.info('Is tracking currently enabled:', isEnabled);
139    } catch (err) {
140    console.error('Failed to enable camera tracking:', err);
141    }
142    ```
143
1442. 监听跟踪变化。
145
146    ```ts
147    const trackingStateCallback = (eventInfo : mechanicManager.TrackingEventInfo) => {
148    switch (eventInfo.event) {
149        case mechanicManager.TrackingEvent.CAMERA_TRACKING_USER_ENABLED:
150        console.info('The user has enabled camera tracking');
151        handleTrackingEnabled();
152        break;
153        case mechanicManager.TrackingEvent.CAMERA_TRACKING_USER_DISABLED:
154        console.info('The user has disabled camera tracking');
155        handleTrackingDisabled();
156        break;
157        case mechanicManager.TrackingEvent.CAMERA_TRACKING_LAYOUT_CHANGED:
158        console.info('Tracking layout has changed');
159        handleLayoutChanged();
160        break;
161    }
162    };
163
164    // 注册跟踪状态监听
165    mechanicManager.on('trackingStateChange', trackingStateCallback);
166    ```
167
1683. 处理跟踪事件。
169
170    ```ts
171    function handleTrackingEnabled() {
172    console.info('Handling trace enable events');
173    // 可以在此处更新UI状态
174    updateTrackingUI(true);
175    }
176
177    function handleTrackingDisabled() {
178    console.info('Handling trace disabled events');
179    // 可以在此处更新UI状态
180    updateTrackingUI(false);
181    }
182
183    function handleLayoutChanged() {
184    try {
185        const newLayout = mechanicManager.getCameraTrackingLayout();
186        console.info('New Tracking Layout:', newLayout);
187        // 根据新布局更新UI
188        updateLayoutUI(newLayout);
189    } catch (err) {
190        console.error('Failed to get new layout:', err);
191    }
192    }
193
194    function updateTrackingUI(enabled: boolean) {
195    // 更新UI显示跟踪状态
196    // To do sth.
197    console.info('Update tracking UI status:', enabled);
198    }
199
200    function updateLayoutUI(layout : mechanicManager.CameraTrackingLayout) {
201    // 更新UI显示布局状态
202    // To do sth.
203    console.info('Update layout UI:', layout);
204    }
205    ```
206
2074. 取消监听。
208
209    ```ts
210    // 取消跟踪状态监听
211    mechanicManager.off('trackingStateChange', trackingStateCallback);
212
213    // 或者取消所有跟踪状态监听
214    mechanicManager.off('trackingStateChange');
215    ```
216
217### 调试验证
218
219为了确保机械设备管理功能正常工作，请按照以下步骤进行调试验证：
220
221**建立连接**
222
2231. 确保机械体配件设备与开发设备通过蓝牙成功配对并建立连接。
2242. 将开发设备正确放置在机械体配件设备上。
225
226**功能验证步骤**
227
2281. **设备列表查询**：调用 `getAttachedMechDevices` 接口查询当前已连接的机械体配件设备列表，验证设备是否正确识别。
2292. **智能拍摄跟踪**：调用 `setCameraTrackingEnabled` 启用摄像头智能跟踪功能，通过 `getCameraTrackingEnabled` 验证状态，测试机械体配件设备是否能跟随目标自动旋转。
230
231**验证结果说明**
232
233- 如果 `getAttachedMechDevices` 返回包含机械体配件设备信息的设备列表，表示设备识别正常。
234- 如果 `getCameraTrackingEnabled` 返回结果为真，表示智能拍摄跟踪启用成功。