识图功能

概览

图像识别是扩博智能零售云服务提供的一项核心能力。要进行图像识别，请按照以下步骤操作：

获取场景编码： 使用scene_code引导我们系统使用适当的人工智能图像识别通道。
创建任务： 创建单张图片识别或多张图片拼接任务。
获取图像识别（IR）结果： 通过调用获取识图结果API手动检索结果，或在创建任务时设置callback_url由我们系统推送结果。回调结果数据结构参考识图结果。有关回调通知的详细信息，请参阅回调通知部分。

注意：

要获取scene_code，您可以通过获取场景列表API检索所有场景，也可以从我们的客户成功经理（CSM）处获取。

获取场景列表

接口说明

检索所有预定义场景，或按照场景名称模糊查询。

请求信息

配置说明	参数值
URL	`/ir/scene/list?name=<scene_name>`
Method	`GET`

请求参数

参数名	类型	描述	是否必填
name	string	场景名称模糊查询	否

响应数据:

`data`数据格式

参数名	类型	描述
results	[]object	场景列表
+ code	string	场景编码
+ name	string	场景名称
+ description	string	场景描述

响应数据样例

json

{
  "code": 0,
  "message": "",
  "data": {
    "results": [
      {
        "name": "货架场景",
        "code": "ST-1-9",
        "description": "这是货架场景的描述"
      }
    ]
  }
}

创建单图任务

接口说明

创建单张图片图像识别任务，请指定request_id为随机的uuid值，该request_id将作为单图任务的task_id。

请求信息

配置说明	参数值
URL	`/ir/recognize`
Method	`POST`
Content-Type	`application/json`

Body参数

参数名	类型	描述	是否必填
request_id	string	请求id，客户需保证唯一性（请使用`uuid`），长度不超过36位（小写）。如果需要发起重试，请保证`request_id`不变。	是
image_url	string	图片的url，通过upload接口上传后的图片url。	是
scene_code	string	场景编码。	是
username	string	访员账号。	否
processed_image_url	string	处理后图片的url。已废弃，可以通过设置`ext_info`字段替换。	否
ext_info	string	其他额外信息，最大长度1000。相关请参考Task额外信息	否
callback_url	string	任务的回调url，具体回调规则请查看callback通知, 回调的具体数据结构查看获取识图结果中的第一层`data`	否
plan_id	string	访店计划id，参考创建访店计划	否

Body参数样例

json

{
  "request_id": "c0c80b91-694c-4f6e-8232-1a039a2731a0",
  "image_url": "https://f-dev.clobotics.cn/4/0040ca4d85f5e5ef7354102f486ef843.jpg",
  "scene_code": "104",
  "processed_image_url": "https://f-dev.clobotics.cn/4/0040ca4d85f5e5ef7354102f486ef877.jpg",
  "ext_info": "{\"key\":\"value\"}",
  "callback_url": "https://www.clobotics.cn/callback",
  "plan_id": "P2506030702016564724"
}

响应数据

`data`数据格式

参数名	类型	描述
task_id	string	任务id

响应数据样例

json

{
  "code": 0,
  "message": "",
  "data": {
    "task_id": "c0c80b91-694c-4f6e-8232-1a039a2731a0"
  }
}

创建拼图任务

接口说明

创建拼图任务，请指定request_id为随机的uuid值，该request_id将作为拼图任务的task_id。还需要提供sub_task_ids、stitching_info和stitching_info_version字段值。

注意：

sub_task_ids 是调用创建单张图片任务时所有子任务的 request_id / task_id 。
确保sub_task_ids里子任务的顺序与Camera SDK返回的图像保持一致，因为拼接的子任务顺序必须与 stitching_info 中的顺序对齐。
stitching_info 由Camera SDK输出。请参考我们的SDK示例项目来使用正确的拼接信息，避免进行任何更改。
如果没有按照正确的顺序，云端服务将无法完成拼接。

请求信息

配置说明	参数值
URL	`/ir/stitching`
Method	`POST`
Content-Type	`application/json`

Body参数

参数名	类型	描述	是否必填
request_id	string	请求Id，客户需保证唯一性（请使用uuid），长度不超过36位（小写）。如果需要发起重试，请保证request_id不变。	是
sub_task_ids	[]string	子任务的taskId集合，子任务数量不能小于2，子任务的顺序必须与stitching_info的顺序保持一致。同一个子任务task_id只能参与一个拼图任务，相同子任务创建不同拼图任务将会报错失败。	是
stitching_info	string	拼图信息，由Camera SDK输出，具体查看Camera SDK文档。注: `stitching_type` 为空或是`5`时，必填。	否
stitching_info_version	int32	拼图信息版本号 `0`: 经典拼图模式 `1`: 视频拼图模式 `3`: 丝融拼图模式 `4`: 优融拼图模式由Camera SDK输出，具体查看Camera SDK文档。注: `stitching_type` 为空或是`5`时，必填。	否
username	string	访员账号。	否
processed_image_url	string	处理后图片的url。已废弃，可以通过设置`ext_info`字段替换。	否
ext_info	string	其他额外信息，最大长度1000。相关请参考Task额外信息	否
callback_url	string	任务的回调url，具体回调规则请查看callback通知, 回调的具体数据结构查看获取识图结果中的第一层`data`	否
plan_id	string	访店计划id，参考创建访店计划	否
stitching_type	int32	拼图类型，默认值为5。 `3`: 简单拼接（所有图片按照第一张图片的高度直接拼接在一起） `4`: 多单图去重不拼接 `5`: 正常拼接	否

Body数据样例

json

{
  "request_id": "b5fed073-d66a-451f-93c0-ea412d7543e8",
  "sub_task_ids": [
    "2b2182a0-9cab-41fd-94c6-4692880a690b",
    "2b2182a0-9cab-41fd-94c6-4692880a690b"
  ],
  "stitching_info": "{\"stitchingInfo\":{\"bestPov\":0,\"pair\":[{\"image1Index\":0,\"image2Index\":1,\"pixelCorrespondence\":[],\"homography\":[1.0064635,-0.095225796,70.384,0.03407375,0.98476404,1.7139097,5.052459E-5,-4.1571122E-5,1]},{\"image1Index\":1,\"image2Index\":2,\"pixelCorrespondence\":[],\"homography\":[0.9902558,-0.02223142,69.341,-0.032897126,1.0594548,-21.226934,-0.00014316723,0.0002628908,1]},{\"image1Index\":2,\"image2Index\":3,\"pixelCorrespondence\":[],\"homography\":[0.9452166,-0.06867031,80.68806,-0.0006102832,0.95038676,5.128851,-0.000043942106,-0.000053319545,1]},{\"image1Index\":3,\"image2Index\":4,\"pixelCorrespondence\":[],\"homography\":[0.99139684,-0.05744228,80.414955,-0.020089298,1.006871,-2.0042527,-0.00008886192,0.00003245073,1]},{\"image1Index\":4,\"image2Index\":5,\"pixelCorrespondence\":[],\"homography\":[0.9550804,-0.064189814,81.82138,-0.02587876,0.97099406,6.294556,-0.00011758251,-0.000049771486,1]},{\"image1Index\":5,\"image2Index\":6,\"pixelCorrespondence\":[],\"homography\":[0.9919336,-0.08287014,81.64814,0.013544433,1.0054679,-2.8793876,-0.000057586047,0.000024841353,1]},{\"image1Index\":6,\"image2Index\":7,\"pixelCorrespondence\":[],\"homography\":[1.0070611,-0.065085396,67.927826,0.009846879,0.9966087,-0.24726827,0.000089298584,-0.0000139677,1]}],\"resize\":0.16666666666666666,\"retryHomo\":0}}",
  "stitching_info_version": 0,
  "processed_image_url": "https://f-dev.clobotics.cn/4/0040ca4d85f5e5ef7354102f486ef877.jpg",
  "ext_info": "{\"key\":\"value\"}",
  "callback_url": "https://www.clobotics.cn/callback",
  "plan_id": "P2506030702016564724",
  "stitching_type": 1
}

响应数据

`data`数据格式

参数名	类型	描述
task_id	string	拼图任务id

响应数据样例

json

{
  "code": 0,
  "message": "",
  "data": {
    "task_id": "b5fed073-d66a-451f-93c0-ea412d7543e8"
  }
}

获取识图结果

接口说明

此API用于手动检索通过创建单图任务或创建拼图任务API提交的任务结果，单图任务和拼图任务两个的响应结果数据结构相同。

注意：

要自动通知结果，您可以在调用创建单图任务或创建拼图任务时设置 callback_url，详细说明见callback通知。

请求信息

配置说明	参数值
URL	`/ir/result/<task_id>?row_sort=desc`
Method	`GET`

路径参数

参数名	类型	描述	是否必填
task_id	string	任务id	是

请求参数

参数名	类型	描述	是否必填
row_sort	string	行排序规则，`desc`=行数从高到低是n ~ 0，`asc`=行数从高到低是1 ~ n。默认`desc`	否
detail	bool	是否需要详细信息，详细信息返回会包含UPC等，默认false	否

响应数据

`data`数据格式

参数名	类型	描述
status	string	任务结果，`PENDING`，`FAIL`，`SUCCESS`
task_id	string	任务id
row_sort	string	行排序规则，`desc`=行数从高到低是n ~ 0,`asc`=行数从高到低是1 ~ n
update_time	int64	结果更新时间（毫秒时间戳）
results	[]object	结果数据，单图任务和拼图任务的results长度是1。
+ image_url	string	识图任务imageUrl
+ processed_image_url	string	处理后图片的url
+ sku_list	[]object	sku列表
+ + sku_id	string	sku id
+ + sku_name	string	sku名称
+ + sku_count	int64	sku数量
+ + category	string	sku类别
+ + manufacturer	string	sku制造商
+ + flavor	string	sku风味
+ + brand	string	sku品牌
+ + sub_brand	string	sku子品牌
+ + pack_type	string	sku包装类型
+ + pack_size	string	sku包装尺寸
+ + sub_category	string	sku子分类
+ + unit	string	sku单位
+ + area	float64	sku总面积
+ + total_width	float64	sku总宽度
+ + upc	string	upc信息
+ locations	[]object	sku坐标列表
+ + box_id	int64	box id
+ + box_type	int32	box type，`0`=未知类型 `1`=模型框 `2`=embedding框 `10`=价签框 `11`=POSM框 `23`=促销信息框
+ + sku_id	string	sku id
+ + linked_box_id	int64	关联的box id，现在只有价签框，后续废弃
+ + linked_box_ids	[]int64	关联的box ids, 比如关联的价签框、POSM框、促销信息框等
+ + price	string	价格
+ + position	object	sku位置
+ + + index	int32	位置序号
+ + + row	int32	行号，具体规则见行列示意图
+ + + col	int32	列号，具体规则见行列示意图
+ + + stacking	int32	堆信息，`0`=无堆放，如果存在堆放，值为1~n
+ + bounding_box	object	坐标框
+ + + x_min	float64	左上角x坐标, 具体位置见box示意图
+ + + y_min	float64	左上角Y坐标, 具体位置见box示意图
+ + + x_max	float64	右下角x坐标, 具体位置见box示意图
+ + + y_max	float64	右下角y坐标, 具体位置见box示意图
+ qualities	[]object	照片质量，具体见Task识图质量说明
+ + id	string	质量id
+ + name	string	质量名称
+ + value	string	质量值
+ metrics	[]object	指标项, 具体见Task识图指标说明
+ + id	string	指标项id
+ + name	string	指标项名称
+ + value	string	指标项值
ext_info	string	额外信息，创建识图任务时的ext_info字段

bounding_box定义

假设拍摄了一张350X640的照片，则(1,1)对应的真实坐标为(350,640)，x_min、x_max、y_min、y_max需要按照相应比例计算真实坐标位置，box示意图如下：
box

position定义

行列的示意图如下：
col_row

注意：

识别结果中每行的列数不保证完全一致。
该图为row_sort为desc时的示意，当row_sort为asc时，从上到下应该是0~6。

响应数据样例

json

{
  "code": 0,
  "message": "",
  "data": {
    "status": "SUCCESS",
    "task_id": "b5fed073-d66a-451f-93c0-ea412d7543e8",
    "row_sort": "desc",
    "update_time": 1668478888000,
    "results": [
      {
        "image_url": "https://f-dev.clobotics.cn/4/0040ca4d85f5e5ef7354102f486ef843.jpg",
        "processed_image_url": "https://f-dev.clobotics.cn/4/0040ca4d85f5e5ef7354102f486ef877.jpg",
        "sku_list": [
          {
            "sku_id": "1047441",
            "sku_name": "Coke Original Sparkling Can 180 ml",
            "sku_count": 7,
            "brand": "Coke",
            "category": "Sparkling",
            "manufacturer": "Coca-Cola",
            "flavor": "",
            "sub_brand": "Original",
            "pack_type": "Can",
            "pack_size": "180",
            "sub_category": "",
            "unit": "ML",
            "area": 12.28,
            "total_width": 10.14,
            "upc": "3700050773"
          }
        ],
        "locations": [
          {
            "sku_id": "1044059",
            "bounding_box": {
              "x_min": 0.46711602807044983,
              "y_min": 0.7578532695770264,
              "x_max": 0.481109082698822,
              "y_max": 0.771846354007721
            },
            "position": {
              "index": 0,
              "row": 1,
              "col": 2,
              "stacking": 0
            },
            "box_id": 0,
            "box_type": 0,
            "linked_box_id": 0,
            "linked_box_ids": [1],
            "price": "2.52"
          },
          {
            "sku_id": "1044059",
            "bounding_box": {
              "x_min": 0.5359848141670227,
              "y_min": 0.7501513361930847,
              "x_max": 0.5499778389930725,
              "y_max": 0.7641443610191345
            },
            "position": {
              "index": 0,
              "row": 1,
              "col": 3,
              "stacking": 0
            },
            "box_id": 0,
            "box_type": 0,
            "linked_box_id": 0,
            "linked_box_ids": [1],
            "price": "1.53"
          }
        ],
        "qualities": [
          {
            "id": "23",
            "name": "test"
          }
        ],
        "metrics": [
          {
            "id": "3",
            "name": "Total facing",
            "value": "38"
          },
          {
            "id": "2",
            "name": "Total empty space",
            "value": "23"
          },
          {
            "id": "5",
            "name": "Total row",
            "value": "5"
          },
          {
            "id": "9",
            "name": "Total door",
            "value": "1"
          }
        ]
      }
    ]
  }
}

通用信息说明

Task额外信息

可以通过ext_info字段设置任务的额外信息，格式为序列化后的json字符串。ext_info中包含保留字段，这些字段可用于识图结果中sku的mapping等功能。

注意：

在定义ext_info中的字段时应避免使用保留字段。

保留字段

参数名	类型	描述
store_name	string	门店名称
store_code	string	门店编码
store_address	string	门店地址
store_channel	string	门店渠道
store_retailer	string	门店零售商
store_region	string	门店区域
store_bottler	string	门店瓶装厂
store_sales_office	string	门店营业所
store_route	string	门店销售线路

保留字段样例

json

{
  "store_name": "门店名称",
  "store_code": "门店编码",
  "store_address": "门店地址",
  "store_channel": "channel",
  "store_retailer": "retailer",
  "store_region": "region",
  "store_bottler": "bottler",
  "store_sales_office": "sales office",
  "store_route": "route"
}

识图功能 ​

概览 ​

获取场景列表 ​

接口说明 ​

请求信息 ​

请求参数 ​

响应数据: ​

data数据格式 ​

响应数据样例 ​

创建单图任务 ​

接口说明 ​

请求信息 ​

Body参数 ​

Body参数样例 ​

响应数据 ​

data数据格式 ​

响应数据样例 ​

创建拼图任务 ​

接口说明 ​

请求信息 ​

Body参数 ​

Body数据样例 ​

响应数据 ​

data数据格式 ​

响应数据样例 ​

获取识图结果 ​

接口说明 ​

请求信息 ​

路径参数 ​

请求参数 ​

响应数据 ​

data数据格式 ​

响应数据样例 ​

通用信息说明 ​

Task额外信息 ​

保留字段 ​

保留字段样例 ​

识图功能

概览

获取场景列表

接口说明

请求信息

请求参数

响应数据:

`data`数据格式

响应数据样例

创建单图任务

接口说明

请求信息

Body参数

Body参数样例

响应数据

`data`数据格式

响应数据样例

创建拼图任务

接口说明

请求信息

Body参数

Body数据样例

响应数据

`data`数据格式

响应数据样例

获取识图结果

接口说明

请求信息

路径参数

请求参数

响应数据

`data`数据格式

响应数据样例

通用信息说明

Task额外信息

保留字段

保留字段样例