动作识别
宠物 IMU 动作识别接口基于智能项圈等穿戴设备采集的 6 轴惯性传感器(3 轴加速度 + 3 轴角速度)时序窗口数据,提供毫秒级、细粒度的宠物姿态与日常行为识别能力。
相比受限于视野、光照、遮挡与隐私的视觉方案,以及仅能提供粗粒度运动量的传统计步器,本服务具备全天候穿戴、超低功耗、无空间盲区等优势,可精准区分躺卧、坐立、行走、小跑、进食、饮水、甩毛、抓挠等相近或短时高频动作,广泛适用于宠物日常活力统计、作息睡眠监测、异常行为初筛及健康趋势预警等场景。
请求地址
POST
/v1/imu/predict
请求参数
请求头
| 请求头 | 类型 | 必填 | 说明 |
|---|---|---|---|
Authorization | string | 是 | 访问凭证,采用 Bearer Token 规范,格式为 Bearer <ACCESS_TOKEN>。 |
Content-Type | string | 是 | 请求体格式,固定为 application/json。 |
请求体 (Body)
json
{
"samples": [
[
-0.322497,
-0.498316,
-0.657535,
-32.217919,
-21.967866,
1.330689
],
...
],
"top_k": 5
}| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
samples | number[][] | 是 | IMU 传感器时序数据滑动窗口矩阵,推荐时间窗口尺寸为 $100 \times 6$(20Hz 采样率下 5 秒连续数据)。每一行为一个采样时间点的 6 轴传感器读数,固定列通道顺序为:[0] ANeck_x, [1] ANeck_y, [2] ANeck_z, [3] GNeck_x, [4] GNeck_y, [5] GNeck_z(即项圈三轴加速度计读数与三轴陀螺仪读数)。 |
top_k | integer | 否 | 返回概率最高的前 $K$ 项预测行为类别数量,默认值为 5。 |
提示:若需要关联具体项圈设备并记录/推送设备行为日志,网关同时提供带设备标识的接口:
POST /v1/imu/predict/{device_id}。
响应示例
json
{
"code": 200,
"message": "success",
"data": {
"behavior": "walk",
"confidence": 0.9421,
"probabilities": {
"walk": 0.9421,
"trot": 0.0312,
"stand": 0.0154,
"run": 0.0085,
"sniff": 0.0028
},
"top_predictions": [
{
"behavior": "walk",
"probability": 0.9421,
"confidence": 0.9421
},
{
"behavior": "trot",
"probability": 0.0312,
"confidence": 0.0312
},
{
"behavior": "stand",
"probability": 0.0154,
"confidence": 0.0154
},
{
"behavior": "run",
"probability": 0.0085,
"confidence": 0.0085
},
{
"behavior": "sniff",
"probability": 0.0028,
"confidence": 0.0028
}
],
"model_version": "v1.2.0",
"inference_time_ms": 15.6
}
}| 参数名 | 类型 | 说明 |
|---|---|---|
code | integer | 业务状态码,200 表示请求及推理处理成功。 |
message | string | 状态提示信息:成功固定为 "success"(网关统一归一化),失败时为安全的中文提示。不要用它做程序判断。 |
data | object | 推理识别结果主体数据对象。 |
data.behavior | string | 置信度最高的主预测行为标识。支持的常见行为类别包括:walk(行走)、trot(小跑)、run(奔跑)、sit(坐立)、stand(站立)、lie(躺卧)、eat(进食)、drink(饮水)、shake(甩毛抖动)、scratch(抓挠挠痒)、sniff(嗅闻嗅探)等。 |
data.confidence | number | 主预测行为的置信度得分,取值范围为 0.0 ~ 1.0。 |
data.probabilities | object | 所有候选行为类别的概率分布字典(Key 为行为英文标识,Value 为对应概率得分)。 |
data.top_predictions | array | 按置信度由高到低排序的前 $K$ 项预测行为列表。 |
data.top_predictions[].behavior | string | 候选行为英文标识。 |
data.top_predictions[].probability | number | 候选行为概率值(0.0 ~ 1.0)。 |
data.top_predictions[].confidence | number | 候选行为置信度得分。 |
data.model_version | string | 当前提供推理服务使用的 IMU 行为识别深度学习模型版本号。 |
data.inference_time_ms | number | 神经网络模型推理耗时,单位为毫秒(ms)。 |
CURL示例:
bash
curl --location 'https://open-api.habitaxx.com/v1/imu/predict' \
--header 'X-Client-Type: wechat_mini' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data '{
"samples": [
[
-0.322497,
-0.498316,
-0.657535,
-32.217919,
-21.967866,
1.330689
],
...
],
"top_k": 5
}'SDK示例:
Python示例:
python
from habitaxx import Habitaxx
# 1. 初始化客户端
client = Habitaxx(
api_key="your_access_token",
base_url="https://open-api.habitaxx.com",
)
# 2. 准备 100x6 窗口的 IMU 传感器采样序列数据
# 列通道依次为: ANeck_x, ANeck_y, ANeck_z, GNeck_x, GNeck_y, GNeck_z
samples = [
[-0.322497, -0.498316, -0.657535, -32.217919, -21.967866, 1.330689],
[-0.320145, -0.495230, -0.654112, -31.845120, -21.503410, 1.210450],
# ... 其余时间步采样数据
]
# 3. 发起行为识别预测请求
response = client.imu.create(
samples=samples,
top_k=5,
)
print(f"识别行为: {response.get('behavior') or response.get('predicted_label')}")
print(f"置信度: {response.get('confidence')}")
print(f"Top 预测列表: {response.get('top_predictions') or response.get('probabilities')}")
# 如需为指定项圈设备推送识别结果:
# device_res = client.imu.for_device(
# device_id="collar_device_001",
# samples=samples,
# top_k=5,
# )Go语言示例:
go
package main
import (
"context"
"fmt"
"log"
"github.com/habitaxx/habitaxx-go"
"github.com/habitaxx/habitaxx-go/option"
)
func main() {
// 1. 初始化 Habitaxx 客户端
client := habitaxx.NewClient(
option.WithAPIKey("your_access_token"),
option.WithBaseURL("https://open-api.habitaxx.com"),
)
// 2. 准备 IMU 时序采样数据 [][6]float64
samples := [][]float64{
{-0.322497, -0.498316, -0.657535, -32.217919, -21.967866, 1.330689},
{-0.320145, -0.495230, -0.654112, -31.845120, -21.503410, 1.210450},
// ... 其余时间步采样数据
}
// 3. 调用 Predict 接口进行动作识别
res, err := client.Predict.New(context.Background(), habitaxx.PredictNewParams{
ImuInferenceRequest: habitaxx.ImuInferenceRequestParam{
Samples: habitaxx.F(samples),
TopK: habitaxx.Int(5),
},
})
if err != nil {
log.Fatalf("IMU 预测失败: %v", err)
}
fmt.Printf("预测响应: %+v\n", res)
// 如需指定设备标识进行推理与上报:
// deviceRes, err := client.Predict.ForDevice(context.Background(), "collar_device_001", habitaxx.PredictForDeviceParams{
// ImuInferenceRequest: habitaxx.ImuInferenceRequestParam{
// Samples: habitaxx.F(samples),
// TopK: habitaxx.Int(5),
// },
// })
}Java示例:
java
package com.example.demo;
import com.habitaxx.HabitaxxClient;
import com.habitaxx.models.ApiResponse;
import com.habitaxx.models.ImuInferenceRequest;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
public class ImuPredictDemo {
public static void main(String[] args) {
// 1. 初始化 HabitaxxClient 并配置访问令牌
HabitaxxClient client = new HabitaxxClient("https://open-api.habitaxx.com");
client.setAccessToken("your_access_token");
// 2. 构造 IMU 六轴时序数据矩阵
List<List<Double>> samples = new ArrayList<>();
samples.add(Arrays.asList(-0.322497, -0.498316, -0.657535, -32.217919, -21.967866, 1.330689));
samples.add(Arrays.asList(-0.320145, -0.495230, -0.654112, -31.845120, -21.503410, 1.210450));
// ... 添加其余采样数据
// 3. 构造请求对象并调用推理
ImuInferenceRequest request = new ImuInferenceRequest(samples, 5);
ApiResponse<Object> response = client.predict().imu(request);
System.out.println("状态码: " + response.getCode());
System.out.println("预测数据: " + response.getData());
// 如需指定设备调用:
// ApiResponse<Object> deviceResponse = client.predict().forDevice("collar_device_001", request);
}
}Node.js示例:
typescript
import Habitaxx from '@habitaxx/sdk';
// 1. 初始化 Habitaxx 客户端实例
const client = new Habitaxx({
apiKey: 'your_access_token',
baseURL: 'https://open-api.habitaxx.com',
});
async function main() {
// 2. 准备 IMU 时序采样矩阵 (N x 6)
const samples: number[][] = [
[-0.322497, -0.498316, -0.657535, -32.217919, -21.967866, 1.330689],
[-0.320145, -0.495230, -0.654112, -31.845120, -21.503410, 1.210450],
// ... 其余采样数据点
];
// 3. 调用行为识别接口
const result = await client.imu.create({
samples,
top_k: 5,
});
console.log('预测响应结果:', result);
// 如需为指定设备推送识别结果:
// const deviceResult = await client.imu.forDevice('collar_device_001', {
// samples,
// top_k: 5,
// });
}
main().catch(console.error);