Visenze API

Visenze API学习

Visenze概述

Visenze是新加坡国立大学的一个孵化项目，主要用于提供图片检索识别方案。一般来说，搭建一个CBIR系统大体需要以下几个关键技术：

• 图片数据库的构建和管理
• 图片检索算法研究，包括特征提取、匹配及索引等算法
• 服务器搭建和维护，与客户机进行交互（Visenze用到了Http和Json协议）

对于一个中小型公司而言，搭建这样一个系统是需要很大的精力和财力的，特别是在图片检索研究方面，很多公司并不具备相关的技术积累。而Visenze提供了一个完整的解决方案，用户只需将自己的图片数据以csv文件的方式上传至Visenze，调用Visenze提供的API即可实现整个图片检索过程。因此，用户无需再关注图片检索的技术细节，可以把工作重心转移到UI设计及其他功能实现上来。当然，个人认为，当公司发展到一定程度的时候，还是要把这些技术掌握到自己手里比较好。

Visenze允许用户为图片添加各种标签（如价钱，来源等等），从这点看还是具有很大的应用价值的。上传格式见下图（除im_name, im_url必须有外，其他标签可任意增删）：

最近准备仿照Visenze搭建一个基于Android的图片检索系统，作为小白，但求多学到点技术。本文先翻译Visenze API Doc， 目的是对其通信协议，数据交互有一个整体认识，便于后续深入研究。
       由于Visenze的服务器源码是非开源的，所以后端代码还是需要自己编写的，希望能写出来吧！
       

一、API概述

1.1 介绍

ViSearch是Visenze的图片检索API，用以提供准确、可靠及可扩展的图片检索。ViSearch API能够使开发者有效地索引并完成图片检索功能。Visenze提供了各种不同语言的SDK，可以方便的应用于Web和移动终端。

1.2 SDK下载

SDK下载地址：

• Java SDK
• Python SDK
• PHP SDK
• IOS SDK
• Android SDK
  当然，也可以访问其JavaScript，IOS和Andorid版上手指南，后续我将重点研究它的Android SDK。

1.3 认证

Visenze为每个ViSearch应用分配了一个唯一的 access key 和 access key。这个密钥对用于认证每个API调用。
Visearch有两个API调用机制。第一个方法是HTTP基本认证（HTTP Basic Auth）——aceess key 和 secret key经过base64编码后，附加在请求头中。这种方法使用简单，但仅仅适用于从后台系统调用API（可能是因为安全问题，前端采用这种方式容易被劫持）。第二种方法是基于签名的认证（signature based authentication）——密钥对用于生成一个数字签名并附加在request URL上。这种方法对于前端和后端调用都较安全。

1.3.1 HTTP Basic Auth

这种认证方式就是标准的HTTP Basic Auth。这里，access key用作用户名，secret key用作认证密码。

在HTTP中，基本认证是一种用来允许Web浏览器或其他客户端程序在请求时提供用户名和口令形式的身份凭证的一种登录验证方式。
在发送之前是以用户名追加一个冒号然后串接上口令，并将得出的结果字符串再用Base64算法编码。例如，提供的用户名是Aladdin、口令是open sesame，则拼接后的结果就是Aladdin:open sesame，然后再将其用Base64编码，得到QWxhZGRpbjpvcGVuIHNlc2FtZQ==。最终将Base64编码的字符串发送出去，由接收者解码得到一个由冒号分隔的用户名和口令的字符串。
虽然对用户名和口令的Base64算法编码结果很难用肉眼识别解码，但它仍可以极为轻松地被计算机所解码，就像其容易编码一样。编码这一步骤的目的并不是安全与隐私，而是为将用户名和口令中的不兼容的字符转换为均与HTTP协议兼容的字符集。

1.3.2 Signature Based Authentication

这种认证方法需要生成一个签名，且对于每次请求只能使用一次。
1.串联成以下字段： secret_key + nonce + date

• secret_key: app的secret key；
• nonce： 一个随机的唯一的字符串，至少8个字符；
• date： 发出请求的UNIX时间戳（以秒为单位），必须保证在做出请求的10分钟内。

2.生成上述串联字符串的HMAC-SHA1，并使用secret key作为HMAC-SHA1的加密密钥。
3.将以下参数附加到HTTP请求中：

• access_key = your_access_key
• nonce = your_generated_nonce
• date = unix_timestamp
• sig = hnmac_sha1_signature

1.4 API 响应

ViSearch API为所有请求返回一个JSON字符串对象，均包含以下属性：

name description status 请求状态，只有三个键值，”OK”, “warning” 或 “fail” method 请求方法 im_id 分配给上传图片的唯一ID，仅仅对uploadsearch可见 result 结果对象的列表，前提是请求成功，即status是”OK” error 错误报表，当请求失败时，即status是”warning”或”fail” page 结果的页数 limit 每页的结果数量 total 返回结果的全部数量

1.5 错误码

一般错误信息：

Message 说明 Invalid access key or secret key. 无效access key或secret key Unauthorized 未授权的认证（不太清楚与上一个的区别） Exceeds image collection size limit. 请求返回结果过多，超出图片集的大小限制 System busy, please try again later. 系统繁忙，请稍后再试 A system error is reported and we are fixing it right now. 系统报错

1.5.1 Data API错误

Data API用于将自己的图片数据插入到数据库中。这个数据库是托管于Visenze的服务器上，开发者可以通过access key 和 secret key访问自己的数据库。并且，每个开发者可以创建不止一个数据库，它们对应于不同的access key 和 secret key。

Code Message 101 未发现编号为trans_id的Transaction(数据库的程序执行单元) 102 未发现im_name图片 103 超出最大插入批量大小，100 104 未插入图片 105 图片参数数量超出最大限制，32 106 {parameter}超出长度限制 107 无效图片名 108 丢失im_url 109 {field}应该是一个数据类型{type} 201 无法通过im_url下载图片 202 不支持的图片编码方式 203 不支持的图片尺寸

1.5.2 Search API错误

Search API提供了图片检索接口。

Message 说明 The query image is still being processed, please try again later. 正在处理查询的图片，请稍后再试 Image not found with im_name. 未发现名字为im_name的图片 Invalid image file format. 无效的图片编码方式 The image format or dimension is invalid. 图片编码或尺寸无效 Invalid image or im_url. 无效的图片或im_url Could not download the image, please try again later. 无法下载图片，请稍后再试 Timeout while downloading image, please try again later. 下载图片超时，请稍后再试 App doesn’t have any images. App不包含任何图片（这里App是指所访问的数据库）

二、 DATA API

ViSearch Data APIs提供了管理图片集的接口。首先你需要准备好一系列的图片及其元数据，然后调用 Insert API，以增加或更新图片。你也可以通过 Insert Status API 来查询图片处理过程，以及处理过程中发生的错误。如果你需要移除图片，你可以调用 Remove API。

注意： 在插入数据前，请配置 [Metadata Fields]`(/setup/#Edit-Metadata-Schema)

2.1 插入图片

2.1.1 POST/insert

这个API用于插入或更新你的图片集数据。

请求参数
关于图片的请求参数必须遵守以下格式：
{key}[index]=value
这里 key 是 im_name, im_url, 或其他字段名； index 是从0开始的图片标号。
对于图片的参数有以下几点限制，这里涉及到了数据库知识，如key：

• 每幅图片的最大键数为32；
• im_name的最大长度是128；
• 每个键值的最大长度是5000；
• 每次调用插入的图片数最大为100；
• 图片的尺寸至少为100*100。为了更好的检索结果，建议尺寸超过800*800；
• 图片文件大小不能超过10MB；
• 支持的图片格式有：bmp, dib, jpeg, jpg, jpe, jp2, png, webp, pbm, pgm, ppm, sr, ras, tiff, tif, gif。

name example description im_name(必需) im_name[0]=example-0 im_name[n]=example-n 在图片集中，每个图片都拥有一个独一无二的名字用作识别码。允许的字符包括[a-z]，[A-Z],[0-9],[-],[_],[.]和 [:]。如果图片集中有一幅图片存在相同名字，则这个图片数据将被更新 im_url(必需) im_url[0]=http://example.com/example-0.jpg im_url[n]=http://example.com/example-n.jpg image url与image name一一对应。Visenze服务器通过image url来下载图片并处理 [metadata fields] brand[0]=my_brand price[0]=199 图片的其他字段，如价钱等

注意 如果你想更新一个已知的图片，没有必要再次插入所有的字段，只需要使用im_name和待更新的字段即可。

2.2 检查插入状态

2.2.1 GET/insert/status/{trans_id}

查询每一次插入事务的处理状态。你可以在每一次调用插入语句的响应中获取 trans_id。

请求参数

如果在插入事务中存在失败的图片，你可以通过以下参数对错误分页：

name type description error_page integer 指定要返回的错误信息的页 error_limit integer 指定每页要返回的错误信息的数目

响应属性

name description trans_id 事务的id processed_percent 已处理的图片占全部图片的百分比 success_count 已成功插入的图片的数量 fail_count 未成功插入的图片的数量 total 事务中的全部图片数量 error_list 在处理图片事务中出现的错误列表 error_page 错误信息的页 error_limit 每页的错误信息数量

2.3 移除图片

2.3.1 POST/remove

这个API用于从图片集中移除图片。移除过程需要5分钟。

请求参数

name example description im_name（必需） im_name[0]=example-0im_name[n]=example-n 移除名字为image names的图片

注意 建议每批次移除100张图片，以优化图片索引速度。（这个应该与Visenze的数据库管理有关吧）

三、 SEARCH API

ViSearch API提供三种图片查询API:
1. 索引查询
提供图片集中一张已存在图片的im_name，然后ViSearch服务器使用这张图片在图片集中进行检索。
2. 上传查询
提供张图片或一个可以访问的图片URL，然后ViSearch服务器使用上传的图片在图片集中检索。
对于每个上传的图片，ViSearch服务器将会返回一个唯一的im_id，后面可以通过这个id做上传检索而无需再次下载图片。
3. 颜色查询
提供一个十六进制的RGB颜色值，然后ViSearch服务器使用颜色在图片集中检索。

3.1 索引检索

3.1.1 GET/search

这个API用图片集中的一张已存在图片进行检索。

请求参数

name example description im_name(必需) im_name=example_name 图片集中待检索图片的名称

3.2 上传检索

3.2.1 POST/uploadsearch

这个API通过上传一张图片或可访问的图片URL在图片集中检索。对于每个上传的图片，ViSearch服务器将会返回一个唯一的im_id，后面可以通过这个id做上传检索而无需再次下载图片。

对于请求和图片有以下几点限制：

• 请求的Content-Type必须是： multipart/from-data
• 图片尺寸至少为100*100
• 为了更好的检索结果，建议图片尺寸大于800*800
• 图片大小不超过10MB

请求参数

name example description image (image file object) 待检索的图片。必须提供图片文件，或im_url，或im_id im_url im_url=http://example.com/exmaple.jpg 待检索图片的下载地址。必须提供图片文件，或im_url，或im_id im_id im_id=example_image_id 对于每个上传图片，服务器会返回一个唯一的im_id，可以利用这个id进一步减少，而无需再次下载图片。必须提供图片文件，或im_url，或im_id box box=0,0,20,20 优化参数，将图片区域限制在x1,yq,x2,y2范围内。图片的左上角坐标为(0,0)

对于每个上传图片，服务器会返回一个唯一的im_id，可以利用这个id进一步减少，而无需再次下载图片。如果你需要使用一张图片进行多次上传检索，可以使用这种方法来节省流量和提高速度。例如，用不同box参数来检索同一幅图片。

注意 如果im_id和图片路径或url同时存在的话，im_id会被视为用于uploadsearch的图片。

3.3 Color Search

3.3.1 GET/colorsearch

请求参数

name example description color(必须) color=012ACF 十六进制6个字符表示颜色

3.4 检索响应

ViSearch返回最多1000张最相近的检索结果。你可以通过分页参数来控制图片检索结果的分页情况。默认的页数是1，并且每页显示结果默认限制为10。
下表展示了响应Json的每个字段。所有Search API的响应属性是一样的。

name example description page “page”:1 返回结果的页数（即用多少页来显示这些结果） limit “limit”:10 每页显示的图片数 total “total”:1000 返回的图片总数：最大是1000 result 参考示例代码 匹配的图片对象列表 qinfo 参考示例代码 查询的图片对象

四、 进阶参数

ViSearch API提供了更多有效的参数来进行进一步的配置：

• 可以使用detection参数进行自动物体识别
• 使用box参数设置图片检索区域
• 可以使用fl查询图片的其他字段（metadata），也可以通过fq来过滤图片
• 可以采用min_score作为检索阈值来过滤不相干结果

下表多这些优化参数进行了总结，并且这些参数适用于所有Search API。

name example description detection detection=all 自动目标识别。 fl fl=brand&fl=price 返回相应字段。如果数据集里不存在这个字段，将被忽略。 fq fq=brand:my_brand&fq=price:0,199 使用字段来过滤结果。如果数据集里不存在这个字段，将被忽略。 score score=ture 如果这个值为true，则每个结果的score都会被附加到响应中来。 score_min score_min=0.5 设置检索的最小阈值。这个值必须在0.0到1.0之间（包括0.0和1.0），否则会保持。默认为0。 score_max score_max=0.8 设置检索的最大阈值。这个值必须在0.0到1.0之间（包括0.0和1.0），否则会保持。默认为1。 page page=1 结果的页数 limit limit=10 每页结果数，最大为1000 qinfo qinfo=true 如果为true，会返回查询信息

4.1 自动目标识别

ViSearch **/uploadsearch**API现在可以检测出待查询图片中的模板。目前可以识别出各种服饰物体，包括Top, Dress, Bottom, Shoe, Bag, Watch, Furniture, Eyewear, Jewlery, Outerwear, Skirt 和 Indian Ethnic Wear。后续Visenze会继续添加其他物体识别功能。
若想检测所有支持的种类，设置参数如下：
detection=all
可以通过Box参数来限制图片检索区域[x1,y1,x2,y2]。如果box参数的高宽均为0，如”box”:[574,224,574,224]，则将其视作一个点，并基于当前点进行目标检测。
你也可以通过设置detection={type}进行特定的目标识别。

4.2 选择框

如果你想检索的目标仅仅占用图片的一小部分，或者在同一张图片中存在其他不相干的图片，检索结果可能会出现错误。使用Box参数可以确定图片的检索区域，以提高准确率。box的坐标是根据上传的图片的原始尺寸确定的。

注意 如果box的坐标是不合法的（负数或超出原始图片），将检索整个图片。

4.3 过滤结果

基于字段过滤检索结果，fq参数可以用于过滤结果：

Type Explanation string Metadata value 必须是: 1. 与查询值完全相匹配，例如Vintage Wingtips与vintage wingtips或vintage并不匹配。2. 多值匹配用OR字符分隔。例如：Wingtips OR Longwing 将会检索与Wingtips或Longwing相匹配的结果 3. 如果含有特殊字符，用双引号分离。例如: “Women’s shoes” OR “Women’s Clothes”将检索与Women’s shoes 或Women’s Clothes相匹配的结果 int Metadata value可以是：1. 恰好等于查询值 2. 与区间相匹配，如1,99，199与查询区间0,199相匹配，但不匹配200，300 float Metadata value可以是：1. 恰好等于查询值 2. 与区间相匹配，如1.0,99.0，199.99与查询区间0,19.999相匹配，但不匹配200.0，300.0 text Metadata value将采用全文检索机制，并支持模糊查询。

4.4 结果分数

ViSearch查询结果采用降序排列，也就是说，从高的分到低得分，从1.0到0.0。每幅图片的分数默认是不返回的。可以通过开启score参数来查询每幅图片的分数：
如果你想通过一个最小得分和最大得分来限制查询结果，可以设定score_min和score_max参数：
| Name | Type | Description |
| score_min | Float | 返回结果的最小得分。默认为0.0 |
| score_max | Float | 返回结果的最高得分。默认为1.0 |

4.5 查询字段

可以通过fl(field list)参数来查询字段：
如果想查询图片结果的全部字段，可以设定get_all_fl参数，并将它设置为true。

注意 只有string，int，和float数据类型可以被查询，text数据类型无法用于查询，只能用来过滤。