Skip to content

1 API列表

1.smaReceivePilotData

2.smaReceivePayloadData

3.smaStartProcess

4.smaStopProcess

5.smaUpdateFuncMask

6.smaGetMediaList

7.smaGetMediaInfo

8.smaGetServerConfig

9.smaGetAIRelated

10.smaSetServerConfig

11.smaUploadAIModelFile

12.smaAddAnnotationElements

13.smaDeleteAnnotationElements

14.smaUploadAIOnnxFile

15.smaStartOnnxtoEngine

16.smaGetOnnxtoEnginePercent

17.smaRequestAiAssistTrack

18.smaStartMultiProcess

19.smaSaveSnapShot

20.smaUpdateArTowerHeight

21.smaUpdateAIPosCor

22.smaSetSeekPercent

23.smaSetVideoPause

24.smaPlaybackMarkRecord

25.pushStreamUrl

26.distributeCfg

2 返回约定

返回值统一为json字符串,样式如下

json
{
"code":int,
"msg":string,
"id":string
}

其中,id为处理的视频流任务唯一ID,该ID会在调用API"SmastartProcess"时返回。Code的含义如下:

java
{
    NotFound = -500,//未找到
    Exception = -400,//代码抛异常
    InvalidArgs = -300,//参数不合法
    SqlFailed = -200,//sql执行失败
    AuthFailed = -100,//鉴权失败
    OtherFailed = -1,//业务代码执行失败,
    Success = 0//执行成功
}

msg为结果信息,API使用者只需要显示msg即可。

3 调用示意图

4 API详解

前言

协议文档里的api接口都是rpc接口,以下所有api接口对外均提供http、mqtt接口,规则如下:

http调用:

url为:http://ip:port/index/api/sma/接口名;POST方式

只有paramsStr,则放到body中以json传输;

还有其它文件如ar_camera等,则paramsStr和其它文件都以form-data传输,json形式的参数列表key为param_json

边应用平台上云http消息体里新增target(目标站点)、pilot_id(飞控ID)字段,都是非必填,字段详细请看边应用平台上云规范文档

示例:发给地面边应用平台消息 http://127.0.0.1:8102/index/api/sma/smaGetMediaList

body里

plain
{
    "secret": "035c73f7-bb6b-4889-a715-d9eb2d1925ee",
    "target": "hdsjdskj", //目标站点(地面站点编号),非必填
    "pilot_id": "123456" //飞控ID,非必填
}

该http回复也是调用hook api,ground_edge_response这个字段代码的就是地面边应用给云边应用的回复,消息体里新增from(接口名)、interface(接口名)、pilot_id字段(使用的飞控ID),都是非必填

mqtt调用:

topic为:/joeap/sma/指控终端/站点编号/cmd;

指控终端id:user_id,给各指控终端分配的id

站点编号:给各边应用平台分配的GUID编号,如3FFBCE3D-5BB2-A800-FA8E-586770BF9793

若只有paramsStr,则按照paramsStr示例正常传输;

若还有其它如ar的kml等,则在paramsStr中增加url字段"ar_vector_url"和"ar_camera_url",用来http下载ar的kml文件和camera文件。

mqtt消息体定义

{ interface:接口名 type:request/response,请求还是回复 target:目标站点 from:源站点 pilot_id:使用的飞控ID message://实际的消息体 { ...... } }

smaReceivePilotData

描述:接收机载元数据

参数:如“metadata-pilot.txt”所示

smaReceivePayloadData

描述: 接收机载元数据

参数:如“metadata-payload.txt”

smaStartProcess

描述:开始任务

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表
ar_filestd::map<std::string, std::string>以键值对形式存储的ar相关文件,在开启AR时才必须传,否则可以传空

paramsStr示例如下:

json
{
  "secret":string,//鉴权码
  "pull_url":string, //拉流地址
  "push_url":string, //推流地址
  "func_mask":string, //功能掩码
}

功能掩码func_mask示例如下,目前去雾、稳像未启用,使用方法:0表示不开启任何功能,1表示只开启AI,3表示开启AI和AR,功能掩码之和即为需要开启的功能

cpp
#define FUNCTION_MASK_AI 0b0000001
#define FUNCTION_MASK_AR 0b0000010
#define FUNCTION_MASK_DEFOG 0b0000100
#define FUNCTION_MASK_STABLE 0b0001000
#define FUNCTION_MASK_VIDEO_RECORD 0b0010000
#define FUNCTION_MASK_SNAP_SHOT 0b0100000
#define FUNCTION_MASK_AI_ASSIST_TRACK 0b1000000

ar_file示例如下:

KeyValue
ar_vector矢量文件kml或kmz
ar_camera相机的config文件

注(本文中所有接口以此为例)

http调用:

url为:http://127.0.0.1:8080/index/api/sma/smaReceivePilotData;只有paramsStr,则放到body中以json传输,若还有其它文件如ar_camera等,则paramsStr和其它文件都以form-data传输,json形式的参数列表key为param_json。

mqtt调用:

topic为:/index/api/sma/smaReceivePilotData;若只有paramsStr,则按照paramsStr示例正常传输;若还有其它如ar的kml等,则在paramsStr中增加url字段"ar_vector_url"和"ar_camera_url",用来http下载ar的kml文件和camera文件。

若是微服务之间,通过主服务传递调用rpc接口,则将paramsStr和ar_file组合成为一个json传递,如下所示:

json
{
  "secret":string,//鉴权码
  "pull_url":string, //拉流地址
  "push_url":string, //推流地址
  "func_mask":string, //功能掩码
  "ar_vector": string, //kml文件
  "ar_camera":string //camera.config文件
}

smaStartMultiProcess

描述:开始多路视频任务

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表
ar_filestd::map<std::string, std::string>以键值对形式存储的ar相关文件,在开启AR时才必须传,否则可以传空

paramsStr示例如下:

json
{
  "secret":string,//鉴权码
  "pull_url":string, //高清拉流地址
  "pull_sd_url":string, //标清拉流地址
  "push_url":string, //高清推流地址
  "push_sd_url":string, //标清推流地址
  "func_mask":string, //功能掩码
}

功能掩码func_mask示例如下,目前去雾、稳像未启用,使用方法:0表示不开启任何功能,1表示只开启AI,3表示开启AI和AR,功能掩码之和即为需要开启的功能

cpp
#define FUNCTION_MASK_AI 0b0000001
#define FUNCTION_MASK_AR 0b0000010
#define FUNCTION_MASK_DEFOG 0b0000100
#define FUNCTION_MASK_STABLE 0b0001000
#define FUNCTION_MASK_VIDEO_RECORD 0b0010000
#define FUNCTION_MASK_SNAP_SHOT 0b0100000
#define FUNCTION_MASK_AI_ASSIST_TRACK 0b1000000

ar_file示例如下:

KeyValue
ar_vector矢量文件kml或kmz
ar_camera相机的config文件

smaStopProcess

述:停止并删除任务

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string, //鉴权码
"id":string,//任务id,由新建任务接口返回
}

smaUpdateFuncMask

述:更新任务的功能,即功能开关

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表
ar_filestd::map<std::string, std::string>以键值对形式存储的ar相关文件,在开启AR时才必须传,否则可以传空

paramsStr示例如下:

json
{
  "secret":string,//鉴权码
"id":string,//任务id,由新建任务接口返回
  "func_mask":string  //功能掩码
}

功能掩码func_mask示例如下,目前去雾、稳像未启用,使用方法:0表示不开启任何功能,1表示只开启AI,3表示开启AI和AR,功能掩码之和即为需要开启的功能

cpp
#define FUNCTION_MASK_AI 0b0000001
#define FUNCTION_MASK_AR 0b0000010
#define FUNCTION_MASK_DEFOG 0b0000100
#define FUNCTION_MASK_STABLE 0b0001000
#define FUNCTION_MASK_VIDEO_RECORD 0b0010000
#define FUNCTION_MASK_SNAP_SHOT 0b0100000
#define FUNCTION_MASK_AI_ASSIST_TRACK 0b1000000

ar_file示例如下:

KeyValue
ar_vector适量文件kml或kmz
ar_camera相机的config文件

smaGetMediaList

述:获取流媒体任务列表

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string //鉴权码
}

返回的流媒体列表信息

json
{
  "code":int, //错误码
  "data":
[
  {
    "pull_url":string, //高清拉流地址
    "push_url":string, //高清推流地址
    "pull_sd_url":string, //标清拉流地址(非必填,多路视频时有)
    "push_sd_url":string, //标清推流地址(非必填,多路视频时有)
    "ai_enable":bool, //是否开启AI
    "ai_enable":bool, //是否开启AR
    "aiassisttrack_enable":bool, //是否开启AI辅助跟踪
    "func_mask": int, //功能掩码
    "id":string, //任务ID
}
{
  ......
}
]
}

smaGetMediaInfo

述:获取指定任务的媒体信息

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string, //鉴权码
  "id":string //任务id
}

返回的媒体信息

json
{
  "code":int, //错误码
  "pull_url":string, //拉流地址
  "push_url":string, //推流地址
  "pull_sd_url":string, //标清拉流地址(非必填,多路视频时有)
  "push_sd_url":string, //标清推流地址(非必填,多路视频时有)
  "ai_enable":bool, //是否开启AI
  "ai_enable":bool, //是否开启AR
  "aiassisttrack_enable":bool, //是否开启AI辅助跟踪
  "func_mask": int, //功能掩码
  "id":string, //任务ID
}

smaGetServerConfig

述:获取服务配置信息

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string, //鉴权码
}

返回的配置信息

json
{
  "code":int, //错误码
  "data":{
      "api.secret": string, //api操作密钥
      "general.TimeZoneNum": string, //时区
      "general.UploadImageTimeDuration": string, //隐患回传间隔秒数
      "general.guid": string, //微服务guid
      "general.server_version": string, //微服务程序版本
      "http.port": string, //http服务端口号

      //wep hook api相关配置
      "hook.enable": bool,  //是否启用hook api
      "hook.on_add_task": string, //开始创建任务
      "hook.on_add_task_result": string, //创建任务结果
      "hook.on_remove_task": string, //主动调用删除任务的结果
      "hook.on_function_updated": string, //更新funcmask掩码结果
      "hook.on_task_stoped": string, //拉不到原始视频流,开始删除任务
      "hook.onnx_to_engine_result": string, //onnx转引擎结果
      "hook.on_save_snapshot_result": string, //快照结果
      "hook.on_create_ar_engine_result": string, //创建arengine的结果
      "hook.ground_edge_response": string, //地面边应用给云端边应用的回复

      //机载端相关配置
      "media.enable_visual_and_infrared": string, //默认为1开启可见光,为2时,开启红外
      "media.infrared_guid": string, //红外视频任务guid
      "media.infrared_input_url": string, //红外视频吊舱输入视频流地址
      "media.infrared_multicast_url": string, //红外视频输出组播视频流地址
      "media.record_file_prefix": string, //录像文件前缀
      "media.record_hd_file_prefix": string, //机载端高清录像文件前缀
      "media.record_path": string, //录像文件夹地址
      "media.record_sd_file_prefix": string, //机载端标清录像文件前缀
      "media.snap_shot_numbers": int, //快照数量
      "media.snap_shot_path": string, //快照保存路径
      "media.visual_guid": string, //可见光视频任务guid
      "media.visual_input_frame_rate": int, //可见光输入视频帧率
      "media.visual_input_url": string, //可见光视频输入视频流地址
      "media.visual_multicast_url": string, //可见光视频输出组播视频流地址

      //rpc 相关配置,从开始端口到结束端口间找到一个可用端口
      "sma_rpc.start_port": string, //rpc开始端口
      "sma_rpc.end_port": string, //rpc结束端口

      //原pilotControl 视频相关配置
      "vehicle.hd_app": string, //高清视频流app
      "vehicle.hd_stream": string, //高清视频流stream, 流媒体视频流为:协议//ip:port/app/stream
      "vehicle.hd_url_pusher": string, //高清视频推流地址
      "vehicle.hd_url_src": string, //高清视频拉流地址
      "vehicle.http_port": string, //流媒体端口,默认为webrtc http端口
      "vehicle.pilot_id": string, //飞控id

      //ai 相关配置
      "ai.YoloVersion": string, //yolo版本
      "ai.aux_YoloVersion": string, //ai辅助ar yolo版本
      "ai.aux_class_num": string, //ai辅助ar 类别数量
      "ai.aux_conf_thresh": string, //ai辅助ar 目标类别置信度阈值
      "ai.aux_engine_file_full_name": string, //ai辅助ar engine完整路径
      "ai.aux_height": string, ///ai辅助ar 输入尺寸的高
      "ai.aux_nms_thresh": string, ///ai辅助ar nms阈值
      "ai.aux_onnx_file_full_name": string, //ai辅助ar onnx完整路径
      "ai.aux_track_buff_len": string, //ai辅助ar  跟踪buf大小
      "ai.aux_track_switch": string, //ai辅助ar 目标跟踪开关
      "ai.aux_width": string, //ai辅助ar 输入尺寸的宽
      "ai.class_num": string, //类别数量
      "ai.conf_thresh": string, //目标类别置信度阈值
      "ai.danger_photo_server_url": string, //隐患回传http地址
      "ai.engine_file_full_name": string, //engine完整路径
      "ai.height": string, //输入尺寸的高
      "ai.nms_thresh": string, //nms阈值
      "ai.onnx_file_full_name": string, //onnx完整路径
      "ai.track_buff_len": string, //跟踪buf大小
      "ai.track_switch": string, //目标跟踪开关
      "ai.width": string, //输入尺寸的宽
      .......
}
}

smaGetAIRelated

述:获取所有AI相关文件路径

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string, //鉴权码
  "find_engine":string, //1表示要查找engine文件,0表示不查找
  "find_onnx":string //1表示要查找onnx文件,0表示不查找
}

返回的相关文件路径信息

json
{
  "code":int, //错误码
  "engine":[
  "/usr/loacl/..."
  .......
]
"onnx":[
    "/usr/loacl/..."
    .......
]
}

smaSetServerConfig

描述:修改配置

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string, //鉴权码
  "http.port": string,
  "http.sslport":string,
  "http.apiDebug":string,
  "rpc.port":string
}

smaUploadAIModelFile

描述:上传AImodel文件

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表
aiStreamstd::stringAI model文件,通过http form-data传递时key为ai_model_file

paramsStr示例如下:

json
{
  "secret":string,
  "model_width": string, //模型宽
  "model_height": string, //模型高
  "class_number": string, //检测的类型数量
  "conf_thresh": string, //检测框的置信度阈值
  "nms_thresh": string, //nms(非极大值抑制)的置信度阈值
  "yolo_version": string //yolo版本
}

smaAddAnnotationElements

述:增加标注要素

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表
ar_filestd::map<std::string, std::string>以键值对形式存储的ar相关文件,这里时camera.config文件和标注要素json文件

paramsStr示例如下:

json
{
  "secret":string,
  "id": string, //任务id
}

ar_file示例如下:

KeyValue
video_mark_data标注要素json文件
ar_camera相机的config文件

标注要素示例如下:

json
{
    "Guid": 透传回云端的GUID,用于云端自己标识标注要素
"ArElementsArray":[
      {
          X: int //图像坐标X
          Y: int //图像坐标Y
          Type: uint8 //坐标类型,当前是点、线还是面
          DotQuantity:uint8 //如果是线或面,表示线、面有几个点
          Category:uint8 //当前点的类型,比如房屋等-暂时未用
        CurIndex:uint8 //当前点序号
          NextIndex: uint8 //下一点序号
          lon: double //经度
          lat: double //纬度
          HMSL: //高度
      },
      {
          ....
      }
]
}

smaDeleteAnnotationElements

述:删除标注要素

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "id": string, //任务id
  "elements_guid": string //添加标注要素时云端下发的guid
}

smaUploadAIOnnxFile

述:上传AIonnx文件

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表
onnxStreamstd::stringAI onnx文件,通过http form-data传递时key为ai_onnx_file

paramsStr示例如下:

json
{
  "secret":string,
  "onnx": ".onnx" //onnx文件后缀
}

smaStartOnnxtoEngine

述:将onnx转换为对应的engine文件

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表
json
{
  "secret":string,
  "is_fp16": string, //是否按照fp_16转换,0表示否,1表示是
}

smaGetOnnxtoEnginePercent

述:获取onnx转换为engine文件的进度

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string
}

返回的进度信息

json
{
  "code":int, //错误码
  "data": float //转换进度,范围 1~100
}

smaRequestAiAssistTrack

述:AI辅助跟踪

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "id": string,
  "track_cmd": string,
  "track_pixelpos_x": string, //跟踪点的图像坐标X
  "track_pixelpos_y": string, //跟踪点的图像坐标Y
}

smaSaveSnapShot

述:AI辅助跟踪

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "id": string,
  "path": string, //快照保存路径
  "numbers": string //快照数
}

smaUpdateArTowerHeight

述:更新AR杆塔高度

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "id": string,
  "is_tower": bool, //
  "tower_height": double, //
  "buffer_sync_height": bool //
}

smaUpdateAIPosCor

述:更改AI辅助吸附位置,默认为中心

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "id": string,
  "ai_pos_cor": int //取值范围0-BOTTOM,1-CENTER,2-TOP
}

smaSetSeekPercent

述:视频跳转,只有http和文件作为视频源时才支持跳转

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "id": string,
  "percent": float //进度,取值范围0-100
}

smaSetVideoPause

述:视频暂停,只有http和文件作为视频源时才支持跳转

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "id": string,
  "pause": int //进度,1-暂停, 0-继续播放
}

smaPlaybackMarkRecord

述:开始回放标注的后处理

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "id": string,
  "playback_address": string //回放文件路径
  "video_out_url": string,//推流地址
  "directory": string, //元数据文件地址,非必填
}

smaSetArLevelDistance

述:设置ar警戒区

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "id": string,
  "level_one_distance": string //一级警戒区,要大于0,一级警戒区要大于等于二级警戒区
  "level_two_distance": string,//二级警戒区,要大于0
}

pushStreamUrl

述:推流地址推送,原pilotControl功能

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "data": {
    "streamUrl": string //推流地址:如果是本地使用时,传空;如果是云平台使用时,传具体的推流地址
  },
  "id": string, //飞控id
}

distributeCfg

述:流媒体分发相关配置,原pilotControl功能

参数

参数名参数类型备注
paramsStrstd::stringjson形式的参数列表

paramsStr示例如下:

json
{
  "secret":string,
  "data": {
    "hdVideoUrl": string, //高清视频源
    "httpPort": int, //流媒体服务器webrtc http端口
    "hdApp": string, //高清视频流地址的app
    "hdStream": string, //高清视频流地址的stream
    "sdVideoUrl": string, //标清视频源 (非必填)
    "rtcPort": int, //webrtc端口,默认8000 (非必填)
    "sdApp": string, //标清视频流地址的app  (非必填)
    "sdStream": string //标清视频流地址的stream  (非必填)
  },
  "id": string, //飞控id
}

5 hook api详解

根据微服务配置里的hoop api地址,如果打开了hook.enable且api有地址,触发相应事件的时候会调用相关hook api接口

on_add_task_result

述:创建任务结果hook api接口

参数

json
{
  "id": string, //任务id
  "code":string, //状态码
  "result": string, //"true"、"false"
  "duration": string, //时长,本地视频才有,暂时没用
  "sd_duration": string,
  "msg": string //信息描述
}

on_add_task

述:开始创建任务hook api接口

参数

json
创建任务的http 接口参数

on_task_stoped

述:拉不到原始视频流,开始删除任务hook api接口

参数

json
{
   "code":string, //状态码
  "id": string, //任务id
  "reason":string, //原因描述
}

on_remove_task

述:主动调用删除任务的结果hook api接口

参数

json
{
   "code":string, //状态码
  "id": string, //任务id
  "result": string, //"true"、"false"
}

onnx_to_engine_result

述:onnx转引擎结果hook api接口

参数

json
{
   "code":string, //状态码
  "msg": string //信息描述
  "result": string, //"success" : "failed"
}

on_save_snapshot_result

述:快照结果hook api接口

参数

json
{
   "code":string, //状态码
  "id": string, //任务id
  "msg": string //信息描述
}

on_function_updated

述:更新funcmask掩码结果hook api接口

参数

json
{
  "code":string, //状态码
  "id": string, //任务id
  "result": string, //"success"、"failed"
  "func_mask": string, //功能掩码
  "msg": string //信息描述
}

on_create_ar_engine_result

述:创建AR引擎结果hook api接口

参数

json
{
  "code":string, //状态码
  "id": string, //任务id
  "result": string, //"success"、"failed"
  "msg": string //信息描述
}

ground_edge_response

述:地面边应用给云端边应用的回复

参数

json
{
  "from":string, //源站点
  "interface": string, //接口名
  "pilot_id": string, //飞控ID
  ...其他的跟http结果一样
}