资讯 社区 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

接口调用

车辆分析私有化部署包部署成功后,即可获得与在线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_codeerror_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] 输入参数不完整
上一篇
部署说明
下一篇
视频专区