视觉接口开发手册

概要

主控板为摄像头设计了两种模式：视频模式和视觉模式。
视频模式就是用于远程视频监控的场合，视觉模式则用于视觉识别处理。
为了节约CPU的计算量，视觉模式的图像被限制为240个像素宽，160个像素高，每个像素值是8位(一个字节，256色模式），具体代表的颜色由色彩空间通道决定。

大部分视觉处理，都会按照下面的基本流程进行：

car.vision.on("Y")，以指定色彩通道打开摄像头。
用car.vision.snap()采样一帧图像，
调用相应的接口进行分析，或者调用car.vision.row()或者car.vision.point()等进行具体的图像数据分析，
执行相应的动作
如果是动态跟踪一类处理，则循环进行前面的动作。

#常见视觉编程流程#打开视觉模式，视觉模式都是8bit模式car.vision.on("Y")#循环采样分析while True:    if car.vision.snap()==False: break
    color = car.vision.getcolor()
    print(color)
    #执行对应的动作
#结束视觉模式car.vision.off()

色彩空间与通道

很多小伙伴都清楚RGB三色原理。这个RGB就是一个色彩空间，而其中单个的R、单个的G、单个的B是三个独立的通道。主控板视觉模式目前仅仅支持一个色彩空间里的一个通道。因为视觉处理的最基础工作就是选择最合适的色彩空间和通道，所以下面这些色彩空间和通道都支持。

RGB色彩空间（R-红色通道、G-绿色通道、B-蓝色通道）

YCbCr色彩空间（Y-灰度通道，Cb-蓝绿通道，Cr-红绿通道）

HSL色彩空间（H-色相通道）

Python接口中涉及到通道配置的参数，则使用上面黄颜色背景字母做为通道名称来配置调用。

视觉接口分类

视觉接口总共分三类：基本操作，视觉识别和绘图标示。

基础操作：类似打开关闭视觉模式、抓取一帧视频、获得指定位置视觉数据等。

视觉识别：类似寻找最大色块、识别二维码等。

绘图标示：类似在获取的视频帧上绘制方块、字母等。

car.vision.on(channel)->bool

打开视觉模式，所有视觉接口使用前都需要先调用这个接口。

参数：

channel 需要使用的色彩空间的通道名称：R、G、B。
返回值处理是否成功。

范例：

#打开视觉模式，并选择YCbCr色彩空间的Y(灰度)通道
car.vision.on('Y')
#打开视觉模式，并选择RGB色彩空间的B(蓝色)通道car.vision.on('B')

car.vision.off()->bool

关闭视觉模式，摄像头会停止工作。

#关闭视觉模式car.vision.off()

car.vision.channel()->str

返回当前视觉模式的色彩空间通道名称。

car.vision.channel()#>>Y

car.vision.height()->int

视觉模式图像的宽度（单位：像素），固定为160像素。

car.vision.getcolor(range)->int

识别摄像头中心区域颜色。

如果是H色彩通道，则返回数量最多的颜色；如果是其它通道，则返回区域平均值。

参数：

range 以摄像头正中心为中心range为半径的范围内的颜色
返回值色彩索引

索引值	颜色
0	未知色彩
1	黑色
2	灰色
3	白色
4	红色
5	橙色
6	黄色
7	绿色
8	青色
9	蓝色
10	紫色
11	品红色

#切换摄像头到RGB全色彩模式car.vision.channel("RGB")#截取一帧视频用于后续分析car.vision.snap()#识别截取的视频帧的x=100,y=50位置的单点的色彩color = car.vision.getcolor(100, 50, 1)print(color)

car.vision.area_find(min, max, noise)->(xs, ys, xe, ye)

寻找当前采样图像中的符合要求的区域，调用本函数前需要先执行采样一帧的命令。

参数：

min 指定的寻找范围的最小值
max 指定的寻找范围的最大值
noise 噪点范围，0代表无噪点，3代表忽略间隔小于等于3的噪点。
返回值 (xs, ys, xe, ye) 符合要求的最大区域的左上角右下角坐标。

car.vision.color_name(color_id:int)->str

根据色彩编号返回色彩名称。

名称和编号对应关系，请参考 getcolor这个接口说明。

car.vision.draw_rect(rect:(x0, y0, x1, y1), color:int, fill:bool)

根据rect指定的矩形位置绘制方框。

参数：

rect 指定矩形的位置
color: 矩形边框的色彩
fill: 矩形是否填充

范例

#以左上角(10,10) 到右下角(20, 20)绘制矩形，边框色彩255，内部填充car.vision.draw_rect((10, 10, 20, 20), 255, True)

car.vision.line_find([rows], min, max, min_width, noise)->(x, y, width)

寻找当前采样图像中的符合要求的水平线段，调用本函数前需要先执行采样一帧的命令。

参数：

rows 指定寻找的水平行，比如80代表寻找第80行，[70, 80]代表依次寻找第70行、第80行。
min 指定的寻找范围的最小值
max 指定的寻找范围的最大值
min_width 指定的寻找水平线段的最小长度
noise 噪点范围，0代表无噪点，3代表忽略间隔小于等于3的噪点。
返回值 x和y代表符合的线段中心点的x和y坐标，width代表符合的线程长度；如果本接口没有找线段到则返回None。

范例：

#寻找第80行，范围在80-125之间长度大于15个像素的水平线段，允许间隔噪点1个像素car.vision.snap()car.vision.line_find(80, 80, 125, 15, 1)#>> (48, 80, 20)  #找到了符合要求的水平线段，线段中心位置x=48, y=80,宽度20个像素。
#依次在第80、70、90行寻找范围在80-125之间长度大于15个像素的水平线段，允许间隔噪点0个像素
car.vision.line_find([80, 70, 90], 80, 125, 15)
#>> None    #没有找到符合要求的水平线段

car.vision.point(x, y)->int

返回当前采样图片里指定坐标位置的值，调用本函数前需要先执行采样一帧的命令。

参数：

x 水平坐标位置，范围等于大于0，到小于240。
y 垂直坐标位置，范围等于大于0，到小于160。
返回值指定位置的值，单字节数值等于大于0到小于256。

范例：

#确定 (x=5, y=10)的像素点是否为白色(0xFF)，它下方的点是否为暗红色(0x00)car.vision.snap()if car.vision.point(5, 10)==0xFF && car.vision.point(5, 11)==0x00):    print("find")

car.vision.print(text:str, [x:int, y:int, color:int, bgcolor:int])

打印文字到视觉帧上面，可以指定打印位置和字体以及背景颜色。

参数：

text 需要打印的文本，仅支持字母数字符号
x, y 指定打印位置，默认为左上角 (0, 0) 开始
color: 指定字体颜色
bgcolor: 指定背景颜色

car.vision.qrcode()->str|None

返回当前采样图片里包含的二维码。

说明：由于视觉模式分辨率比较小，二维码请使用10个字母以内。根据二维码的协议，单纯使用大写字母、数字会让二维码尺寸更小。

参数：

返回值如果识别到二维码，则返回二维码文本，如无，则返回None

car.vision.row(row_index)->list

返回当前采样图片里指定行的全部点的值，调用本函数前需要先执行采样一帧的命令。

参数：

row_index 指定行的索引，范围等于大于0到小于160。
返回值指定行的所以点值的列表

范例：

#从第80行依次查找，直到遇到值为0xFF的点car.vision.snap()data = car.vision.row(80)for i in range(240):    if data[i]==0xFF: print("find")

car.vision.snap()->bool

采样一帧图像用于后续处理。

各种视觉处理的第一步就是先执行这个采样接口，采样一帧。
采样后，该帧数据会被冻结在内存中供后续各种图像处理。

car.vision.width()->int

视觉模式图像的宽度（单位：像素），固定为240像素。