接口调用
更新时间：2024-06-19
车辆分析私有化部署包部署成功后，即可获得与在线API基本相同的接口，相关接口将会启动，即可参考本文档开始调用测试。
车辆分析的各个接口拆分为不同的私有部署包，车型识别、车辆检测、车流统计对应3个不同的部署包，方便选取所需能力灵活应用。
接口格式说明
变量类型定义
| 类型 | 定义 |
|---|---|
| string | 普通的字符串，可能会有长度要求，具体参见接口说明中的备注 |
| uint32 | 整形数字，最大取值为4字节int。自然数 |
| int64 | 整形数字，最大取值为8字节int。允许负数 |
| json | 无论是request还是response中某个字段定义为json，那么它其实是一个json格式的字符串，需要二次解析 |
| array | request的query中表示array请使用key[] 。response的json中的array即为jsonArray |
| double | 双精度，小数点后最大8位四舍五入 |
请求参数格式如下：
json
req_array = {
'appid': '123456',
'logid': logid,
'format': 'json',
'from': 'test-python',
'cmdid': '123',
'clientip': '0.0.0.0',
'data': base64.b64encode(data),
}
req_json = json.dumps(req_array)python代码示例如下：
import base64
import json
from proto import general_classify_client_pb2
//输入图片为01.jpg
image_file = "01.jpg"
//将图片内容读取至image_data
with open(image_file, 'rb') as f:
image_data = f.read()
proto_data = general_classify_client_pb2.GeneralClassifyRequest()
proto_data.image = image_data
data = proto_data.SerializeToString()
logid = random.randint(1000000, 100000000)
# 将data转为json，并进行base64编码
req_array = {
'appid': '123456',
'logid': logid,
'format': 'json',
'from': 'test-python',
'cmdid': '123',
'clientip': '0.0.0.0',
'data': base64.b64encode(data),
}
# 最终应该传入http body的内容
req_json = json.dumps(req_array)返回格式
- error_code、error_msg即错误码和错误描述，详细含义请参考错误码表, error_code为0代表请求成功
- result是接口返回的详细信息, 格式为数组。
- log_id是请求的日志id, 13位长(bigint), 用于定位请求。
{
"error_code" : 0, //错误码 0代表成功
"error_msg" : "SUCCESS", //错误信息
"result" : {...} //返回结果 具体内容详见相关接口
"log_id" : 3535325235 //请求的日志id
"timestamp" : 1512391548 //请求到达的时间戳 精确到秒级
"cached" : 0 //未启用 无需处理
}返回内容解析：
res_json = json.loads(response)
if res_json['err_no'] == 0:
proto_result = general_classify_client_pb2.GeneralClassifyResponse()
proto_result.ParseFromString(base64.decodestring(res_json['result']))
res_json['result'] = protobuf_to_dict(proto_result)接口调用说明
车型识别
检测图片中的主体车辆位置，识别车辆品牌型号（如宝马X3）、年份、颜色信息，可识别近3000款常见车型（小汽车为主）。
调用接口的地址示例：[192.168.0.1]:8125/GeneralClassifyService/classify，其中ip需要替换为用户自己服务器的ip，端口默认为：8125，可以在配置文件car.conf中修改
路径
/GeneralClassifyService/classify
请求参数
| 参数 | 是否必选 | 类型 | 可选值范围 | 说明 |
|---|---|---|---|---|
| image | 是 | string | 0-255彩色图像（base64编码） | 图像数据，base64编码，size＞50。异常：若图片尺寸长或宽小于50pixel，会提示尺寸过小 |
| top_num | 否 | int | 返回车型识别结果的个数，按照概率高低排序；默认是5 |
请求参数构造及python代码示例
请求参数为json格式，请求时请将Content-Type设置为application/json格式。
请求参数格式如下：
json
{
'data':base64encode(
{
"image" : base64encode(binary image data),
"top_num" : 5,
}
)
}python代码示例如下：
python
import base64
import json
# 输入图片为/home/work/01.jpg
image_file = "/home/work/01.jpg"
# 将图片内容读取至image_data
with open(image_file, 'rb') as f:
image_data = f.read()
data = {
# 将image_data进行base64编码
"image": base64.b64encode(image_data),
# 设置车型识别输出结果的前几位结果
"top_num": 5,
}
request_body = {
# 将data转为json，并进行base64编码
"data": base64.b64encode(json.dumps(data))
}
# 最终应该传入http body的内容
print json.dumps(request_body)返回参数
| 字段 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| color | 是 | string | 车型颜色，例如：红色 |
| location | 是 | object | 车辆在图片中的位置信息 |
| +height | 是 | float | 目标检测框高度 |
| +left | 是 | float | 目标检测框左坐标 |
| +top | 是 | float | 目标检测框顶坐标 |
| +width | 是 | float | 目标检测框宽度 |
| result | 是 | object[] | 车型识别结果数组 |
| +class_name | 否 | string | 车型名称，如：宝马x6 |
| +probability | 否 | float | 置信度，取值范围0-1 |
| +year | 否 | string | 年份 |
返回示例
json
{
"color":"白色",
"location":
{
"height":445.0488586425781,
"left":0.0,
"top":267.1705017089844,
"width":1256.413696289062
},
"result":[
{
"class_name":"别克威朗(Verano)",
"probability":0.9993143677711487,
"year":"2017"
},
{
"class_name":"别克英朗",
"probability":9.359556133858860e-05,
"year":"2017"
},
{
"class_name":"通用(别克昂科拉)Mokka",
"probability":3.383650619070977e-05,
"year":"2017"
},
{
"class_name":"长城C50",
"probability":1.912148218252696e-05,
"year":"2012-2016"
},
{
"class_name":"吉利博瑞",
"probability":1.428041650797240e-05,
"year":"2015-2017"
}
],
"type_name":"fg-car-online"
}错误返回值
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| err_msg | string | 是 | 错误信息，只在异常中出现（参考错误码） |
| err_code | unit32 | 是 | 错误码，只在异常中出现（参考错误码） |
错误码表
| err_code | err_msg | 名称 | 解释 |
|---|---|---|---|
| 1 | 无 | GENERAL_CLASSIFY_CONF_FILE_ERR | 部署包中配置文件错误 |
| 2 | car_damage_service[status:fail to parse rec_returned value] | GENERAL_CLASSIFY_PREDICT_ERR | 车型识别服务错误，无法解析识别结果 |
| 3 | fg_car_service[status:image size < 50] | GENERAL_CLASSIFY_IMAGE_ERR | 图像尺寸小于50像素 |
| 4 | fg_car_service[status:parse pb error] | GENERAL_CLASSIFY_PARSE_PB_ERR | 无法解析请求 |
| 5 | fg_car_service[status: topnum type error] | GENERAL_CLASSIFY_REQUEST_TYPE_ERR | 车型识别中设置的top_num的类别错误，应为uint |
| 6 | ImageClassify[status: authenticate error] | IMAGECLASSIFY_AUTHENTICATE_ERR | 鉴权失败 |
车辆检测
传入单帧图像，检测图片中所有机动车辆，返回每辆车的类型和坐标位置，可识别小汽车、卡车、巴士、摩托车、三轮车5类车辆，同时可定位小汽车、卡车、巴士的车牌位置。
当前主要适用于普通监控场景，如道路、停车场等，无人机高空拍摄的图片，因车辆目标较小，识别效果欠佳，后续会扩展面向高空拍摄场景的模型。
调用接口的地址示例：[192.168.0.1]:8125/GeneralClassifyService/classify，其中ip需要替换为用户自己服务器的ip，端口默认为：8125，可以在配置文件car.conf中修改
路径
/GeneralClassifyService/classify
请求参数
| 参数 | 是否必选 | 类型 | 可选值范围 | 说明 |
|---|---|---|---|---|
| image | 是 | string | 0-255彩色图像（base64编码） | 图像数据，base64编码，size＞50。异常：若图片尺寸长或宽小于50pixel，会提示尺寸过小 |
请求参数构造及python代码示例
请求参数为json格式，请求时请将Content-Type设置为application/json格式。
请求参数格式如下：
json
{
'data':base64encode(
{
"image" : base64encode(binary image data),
}
)
}python代码示例如下：
python
import base64
import json
# 输入图片为/home/work/01.jpg
image_file = "/home/work/01.jpg"
# 将图片内容读取至image_data
with open(image_file, 'rb') as f:
image_data = f.read()
data = {
# 将image_data进行base64编码
"image": base64.b64encode(image_data),
}
request_body = {
# 将data转为json，并进行base64编码
"data": base64.b64encode(json.dumps(data))
}
# 最终应该传入http body的内容
print json.dumps(request_body)返回参数
| 字段 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| objects | 是 | vector | 检测到的目标信息 |
| +height | 是 | int32 | 目标检测框高度 |
| +left | 是 | int32 | 目标检测框左坐标 |
| +top | 是 | int32 | 目标检测框顶坐标 |
| +width | 是 | int32 | 目标检测框宽度 |
| +label | 是 | int32 | 目标物体类型：1 - car（小汽车）;2 - mediumbus（中巴）;3 - bus（大巴）;4 - minivan（小型货车）;5- truck（卡车）;6 - heavytruck（重型卡车）;7 - tricycle（三轮车）;8 - motorbike（摩托车）;9 - bicycle（自行车）;10 - plate（车牌） |
| +prob | 是 | float | 置信度分数，取值0-1 |
返回示例
json
{
'type_name': u'fg-car-det-surveillance',
'objects': [
{
'top': 413,
'height': 265,
'width': 506,
'label': 1,
'prob': 0.5790910124778748,
'left': 1389
},
{
'top': 144,
'height': 34,
'width': 53,
'label': 1,
'prob': 0.5447509288787842,
'left': 568
}
]
}错误返回值
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| err_msg | string | 是 | 错误信息，只在异常中出现（参考错误码） |
| err_code | unit32 | 是 | 错误码，只在异常中出现（参考错误码） |
错误码表
| err_code | err_msg | 解释 |
|---|---|---|
| GENERAL_CLASSIFY_REQUEST_ERR = 216100 | fg_car_service[status:parse pb error] | 输入错误 |
| GENERAL_CLASSIFY_IMAGE_ERR=216201 | fg_car_service[status:no image] fg_car_service[status:image empty] fg_car_service[status:image size < 50] |
图像出错 |
| GENERAL_CLASSIFY_BACKEND_ERROR = 216400 | conf文件读取错误 | |
| GENERAL_CLASSIFY_SUCCEED=0 | fg_car_service[status:succeed] | 成功 |
车流量统计
- 车辆检测与追踪：检测图像中的所有车辆，识别每辆车的类型和坐标位置，可根据连续的视频图片序列，跟踪车辆轨迹。
- 动态车流量统计：在原图中指定区域，根据车辆轨迹判断驶入/驶出区域的行为，统计各类车辆进出区域的数量，可返回含统计值和跟踪框的渲染图。
调用接口的地址示例：[192.168.0.1]:8120/GeneralClassifyService/classify，其中ip需要替换为用户自己服务器的ip，端口默认为：8120
路径
/GeneralClassifyService/classify
请求参数
| 字段 | 必需 | 类型 | 取值范围 | 说明 |
|---|---|---|---|---|
| dynamic | 是 | bool | True/False | True：动态车流检测，返回总车辆数、跟踪ID、动态车流；False：只进行静态车辆检测，返回总车辆数 |
| appid | 否 | string | 区分不同的应用，无实际含义 | |
| case_id | 当dynamic为True时，必需 | int | 任务ID（服务通过case_id区分不同视频流，用户自拟，不同序列间不可重复） | |
| case_init | 当dynamic为True时，必需 | bool | True/False | 每个case的初始化信号，为true时对该case下的跟踪算法进行初始化，为false时从redis上重载该case的跟踪状态。当为false且redis上读取不到相应case的信息时，直接重新初始化。redis时效6000s |
| cmd | 当dynamic为True时，必需 | string | track, finish | 跟踪过程使用track命令，结束时使用finish命令。当前版本track和finish没有区别 |
| image | 是 | string | 0-255彩色图像（base64编码），size>50 | 输入数据中["image"]字段，图像数据，base64编码。异常：若图片尺寸长或宽小于10pix或大于4096pix会提示尺寸不在范围内。支持图片格式：jpg，bmp，png。 注意：图片的base64编码是不包含图片头的，如（data:image/jpg;base64,） |
| show | 可选 | bool | True/False | 是否返回结果图（含统计值和跟踪框）。缺省时不返回。 |
| area_static | 可选 | array(int) | 原图像素范围 | 静态车流统计时，只返回区域内的车辆数，格式为[[x1,y1,x2,y2,...,xn,yn]]，按顺序依次给出每个顶点的xy坐标（尾点和首点相连），形成闭合多边形区域。服务会做范围（顶点左边需在图像范围内）及个数校验（数组长度必须为偶数，且大于3个顶点）。暂时只支持每次单个多边形区域建议设置矩形框，即4个顶点。坐标取值不能超过图像宽度和高度，比如1280的宽度，坐标值最大到1279 |
| area_dynamic | 当dynamic为True时，必需 | array(int) | 原图像素范围 | 动态车流统计时，进出区域的车辆会被统计，格式为[[x1,y1,x2,y2,...,xn,yn]]，按顺序依次给出每个顶点的xy坐标（尾点和首点相连），形成闭合多边形区域。服务会做范围（顶点左边需在图像范围内）及个数校验（数组长度必须为偶数，且大于3个顶点）。暂时只支持每次单个多边形区域，建议设置矩形框，即4个顶点。坐标取值不能超过图像宽度和高度，比如1280的宽度，坐标值最大到1279 |
请求参数构造及python代码示例
请求参数为json格式，请求时请将Content-Type设置为application/json格式。
请求参数格式如下：
json
{
req_array = {
'appid': '1234567',
'logid': logid,
'format': 'json',
'from': 'tet-python',
'cmdid': '123',
'clientip': '0.0.0.0',
'data': req_data
}
}python代码示例如下：
python
import base64
import json
# 输入图片
image_file = "01.jpg"
# 将图片内容读取至image_data
with open(image_file, 'rb') as f:
image_data = f.read()
data={}
#准备request data
data["appid"] = "123456"
data["image"] = base64.b64encode(image_data)
data["dynamic"] = False
data["cmd"] = "track"
data["case_id"] = 1322323
data["case_init"] = True
req_data = base64.b64encode(json.dumps(data))
request_body = {
'appid': '1234567',
'logid': "202112061234",
'format': 'json',
'from': 'tet-python',
'cmdid': '123',
'clientip': '0.0.0.0',
'data': req_data
}
# 最终应该传入http array的内容
req_json = json.dumps(request_body)返回参数
返回值格式：
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
| err_msg | string | 是 | 错误信息（参考错误码） |
| err_no | uint32 | 是 | 错误码（参考错误码） |
| result | json string | 是 | 返回结果信息，格式详见后文“示例返回值”。 |
| image | string | 否 | 0-255彩色图像（base64编码的jpg编码文件） |
正确返回值说明：
| 字段 | 类型 | 说明 |
|---|---|---|
| vehicle_num | object | 检测到的车辆数目（单图） |
| +car | int | 小汽车数量 |
| +truck | int | 卡车数量 |
| +bus | int | 巴士数量 |
| +motorbike | int | 摩托车数量 |
| +tricycle | int | 三轮车数量 |
| vehicle_info | object数组 | 每个框的具体信息 |
| +location | object | 跟踪到的车辆检测框位置 |
| ++left | int | 车辆检测框左坐标 |
| ++top | int | 车辆检测框顶坐标 |
| ++width | int | 车辆检测框宽度 |
| ++height | int | 车辆检测框高度 |
| +ID | int | 车辆的ID编号 |
| +type | string | 车辆类别 |
| +score | float | 类别置信度 |
| vehicle_count | object | 进出区域的车流统计 |
| +car | object | 小汽车 |
| ++in | int | 当前帧相应车辆驶入区域的瞬时数量，如要计算某一段时间内进入区域的累计车辆数，可基于连续帧图片的返回结果计算得到（下同） |
| ++out | int | 当前帧相应车辆驶出区域的瞬时数量，如要计算某一段时间内离开区域的累计车辆数，可基于连续帧图片的返回结果计算得到（下同） |
| +truck | object | 卡车 |
| ++in | int | |
| ++out | int | |
| +bus | object | 巴士 |
| ++in | int | |
| ++out | int | |
| +motorbike | object | 摩托车 |
| ++in | int | |
| ++out | int | |
| +tricyle | object | 三轮车 |
| ++in | int | |
| ++out | int | |
| image | string(jpg encode，base64) | 结果图，含跟踪框和统计值（渲染jpg图片byte内容的base64编码，请求端得到后先做base64解码再以字节流形式imdecode） |
渲染结果图说明
画面里刚出现的车辆检测框都是红色，被跟踪锁定之后会变成其他颜色（颜色随机，不同颜色没有特定规律），模型根据同颜色框的运动轨迹来判断进出移动方向；车辆被跟踪锁定后，检测框上方会出现车辆的ID编号，ID的取值逻辑为：每个case从1开始，不同车辆向上递增但不一定连续。
返回示例
dynamic为true时，执行连续帧动态跟踪和车流统计，前后帧之间同一目标具有相同ID
未检测到任何车辆：
{
"vehicle_num":
{
"car":0,
"truck":0,
...
"tricycle":0
},
"vehicle_info":[],
“vehicle_count”:
{
"car":
{
"in":0,
"out":0
},
"truck":
{
"in":0
"out":0
},
...
}
}检测到1辆小汽车、1辆卡车，无轨迹，无车进出区域：
{
"vehicle_num":
{
"car":0,
"truck":1,
...
"tricycle":0
},
"vehicle_info":[],
“vehicle_count”:
{
"car":
{
"in":0,
"out":0
},
"truck":
{
"in":0
"out":0
},
...
}
}检测到2辆小汽车、1辆卡车，3条轨迹，1辆卡车离开区域：
{
"vehicle_num":
{
"car":2,
"truck":1,
...
"tricycle":0
},
"vehicle_info":
[
{
"ID":3
"location":
{
"left": 100,
"top": 200,
"width": 200,
"height": 400,
}
"type": "car"
},
{
"ID": 5
"location":
{
"left": 400,
"top": 200,
"width": 200,
"height": 400,
}
"type": "car"
},
{
"ID": 6
"location":
{
"left": 600,
"top": 200,
"width": 300,
"height": 400,
}
"type": "truck"
}
],
“vehicle_count”:
{
"car":
{
"in":0,
"out":0
},
"truck":
{
"in":0
"out":1
},
...
}
}dynamic为false时，只执行单帧检测，ID仅为单帧图像内不同车辆的序号，前后帧之间ID无关联
未检测到任何车辆：
{
"vehicle_num":
{
"car":0,
"truck":0,
...
"tricycle":0
},
"vehicle_info":[],
“vehicle_count”:
{
"car":
{
"in":0,
"out":0
},
"truck":
{
"in":0
"out":0
},
...
}
}检测到2辆小汽车、1辆卡车：
{
"vehicle_num":
{
"car":2,
"truck":1,
...
"tricycle":0
},
"vehicle_info":
[
{
"ID":0
"location":
{
"left": 100,
"top": 200,
"width": 200,
"height": 400,
}
"type": "car"
},
{
"ID": 1
"location":
{
"left": 400,
"top": 200,
"width": 200,
"height": 400,
}
"type": "car"
},
{
"ID": 2
"location":
{
"left": 600,
"top": 200,
"width": 300,
"height": 400,
}
"type": "truck"
}
],
“vehicle_count”:
{
"car":
{
"in":0,
"out":0
},
"truck":
{
"in":0
"out":0
},
...
}
} 错误返回值
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| err_msg | string | 是 | 错误信息，只在异常中出现（参考错误码） |
| err_code | unit32 | 是 | 错误码，只在异常中出现（参考错误码） |
错误码表
| err_no | value | err_msg | 解释 |
|---|---|---|---|
| GENERAL_CLASSIFY_SUCCEED | 0 | fg-jinlong[status:person counting succeed] | 整体流程成功 |
| GENERAL_CLASSIFY_CONF_FILE_ERR | 216401 | GeneralClassifyProcessorFactory[status:reading conf file error] | 读取conf文件出错 |
| GENERAL_CLASSIFY_BBOX_PREDICT_ERR | 216401 | GeneralClassify[status: bbox predict error!] | boudingbox检测过程出错 |
| GENERAL_CLASSIFY_IMAGE_EMPTY_ERR | 216200 | fg-jinlong[status:empty image] | 输入数据中不存在“image”字段 |
| GENERAL_CLASSIFY_IMAGE_FORMAT_ERR | 216201 | fg-jinlong[status:image format error] | 读取base64输入图片出错 |
| GENERAL_CLASSIFY_IMAGE_SIZE_ERR | 216202 | fg-jinlong[status:image size not between 10 and 4096] | 输入图片尺寸不在允许范围之内 |
| GENERAL_CLASSIFY_AUTH_ERR | 216401 | fg-jinlong[status:auth verify error] | 鉴权出错 |
| GENERAL_CLASSIFY_FEATURE_EXTRACT_ERR | 216401 | GeneralClassify[status: re-id feature extract error!] | 特征提取过程出错 |
| GENERAL_CLASSIFY_REDIS_ERR | 216401 | fg-jinlong[status:access redis error] | 访问redis过程出错 |
| GENERAL_CLASSIFY_INPUT_FORMAT_ERR | 216100 | fg-jinlong[status:invalid input param] | 输入参数无效 |
| GENERAL_CLASSIFY_INPUT_ABSENCE_ERR | 216101 | fg-jinlong[status:not enough input param] | 输入参数不完整 |