SungemSDK-Python

开发指南

hsapi 的包结构如下:

hsapi
├── __init__.py
├── core
│   ├── __init__.py
│   ├── base.py
│   ├── device.py
│   └── graph.py
├── high
│   ├── __init__.py
│   ├── net.py
│   └── task.py
└── easy
    ├── __init__.py
    └── prefab.py
  • core 模块为底层接口
  • high 模块为高层接口,抽象了一个神经网络基类,简化操作流程
  • easy 模块提供了一些使用内置神经网络比较简便的类和方法

底层接口

管理设备 Device实例

import numpy
import hsapi as hs # 导入 hsapi 模块, 注意导入路径

# 获取角蜂鸟设备
device_list = hs.EnumerateDevices() # 获取所有已连接的角蜂鸟
device = hs.Device(device_list[0])

# 打开角蜂鸟设备
device.OpenDevice()

"""
# [可选,根据业务需要]
# 读取角蜂鸟设备自带的摄像头的图像 
image = device.GetImage(zoomMode=True) # zoomMode: True(640x360) False(1920x1080)
"""

# 操作神经网络资源、处理数据、业务逻辑等
...

# 关闭设备,角蜂鸟设备将会自动重置
device.CloseDevice()

管理神经网络资源 Graph实例

  • 单角蜂鸟多模型:同一个 Device实例 加载多个Graph文件,获取多个 Graph实例
  • 多角蜂鸟多模型:不同的 Device实例 加载不同的Graph文件,获取对应的 Graph实例
# 加载Graph文件, 获取Graph实例
with open('Graph文件路径', mode='rb') as f:
    data = f.read()
graph = device.AllocateGraph(data, scale, mean) # scale、mean 图像预处理参数

# 神经网络的图像输入,这里有两种方式 [2选1]
# 1. 加载外部图像,这里以读取USB摄像头为例
"""
import cv2
capture = cv2.VideoCapture(0)
_, image = capture.read()

image = image_preprocess(image) # 把图像预处理,处理成神经网络需要的格式和大小
graph.LoadTensor(image.astype(numpy.float16), None) # 加载图像作为神经网络的输入
"""
# 2. 使用角蜂鸟自带的摄像头作为输入
# 使用自带的摄像头作为输入, 返回图像
image = graph.GetImage(True)  # zoomMode: True(640x360) False(1920x1080)

# 读取神经网络输出
output, _ = graph.GetResult()

# 解析神经网络输出,实现业务逻辑
...

# 释放神经网络资源
graph.DeallocateGraph()

简单的接口调用流程

# 单角蜂鸟单模型
import cv2, numpy
import hsapi as hs # 导入 hsapi 模块, 注意导入路径

scale = 0.007843 # 图像预处理参数
mean = -1.0 # 图像预处理参数

device_list = hs.EnumerateDevices() # 获取所有已连接的角蜂鸟
device = hs.Device(device_list[0]) # 获取Device实例

device.OpenDevice() # 打开角蜂鸟设备

with open('Graph文件路径', mode='rb') as f:
    data = f.read()
graph = device.AllocateGraph(data, scale, mean) # 获取Graph实例

try:
    while True:
        # 使用自带摄像头作为输入
        image = graph.GetImage(True) # 用角蜂鸟设备图像作为神经网络输入
        output, _ = graph.GetResult() # 获取神经网络输出结果
        print(output)
        cv2.imshow("horned-sungem", image)
        cv2.waitKey(1)
finally:
    graph.DeallocateGraph() # 释放神经网络资源
    device.CloseDevice() # 关闭角蜂鸟设备

高层接口

Net 是个抽象类,封装了部分简单的设备操作。
基于该类可实现一个自己的神经网络类,可参考 easy.prefab 模块中预置的模型类。

预置模型 - 人脸检测

# 单角蜂鸟单模型
import cv2, numpy 
from hsapi import FaceDetector # 导入模块

# 可通过graphPath属性来指定模型路径,默认路径在examples/graphs下
net = FaceDetector(graphPath="./graph_face_SSD", zoom = True, thresh=0.55) # 创建人脸检测网络

try:
    while True:
        # 使用自带摄像头作为输入
        result = net.run(image=None) # 使用角蜂鸟自带设备作为输入,获取网络输出
        image = net.plot(result) # 根据输出结果绘制图像
        cv2.imshow("FaceDetector", image)
        cv2.waitKey(1)
finally:
    net.quit() # 退出神经网络,释放资源,重置设备

预置模型 - 人脸检测 + 物体检测

# 单角蜂鸟多模型
import cv2
import hsapi as hs

device_list = hs.EnumerateDevices() # 获取所有已连接的角蜂鸟
device = hs.Device(device_list[0]) # 获取Device实例

face_net = hs.FaceDetector(device=device, zoom = True, thresh=0.55) # 创建人脸检测网络
obj_net = hs.ObjectDetector(device=device, zoom = True, thresh=0.55) # 创建物体检测网络

"""
多角蜂鸟多模型: 初始化 Net 时使用不同的 Device 实例即可
"""

capture = cv2.VideoCapture(0) # 获取USB摄像头

try:
    while True:
        # 使用USB摄像头作为输入
        _, image = capture.read() # 读取USB摄像头图像数据
        face_result = face_net.run(image) # 将图像输入到人脸检测网络中
        obj_result = obj_net.run(image) # 将图像输入到物体检测网络中

        image = face_net.overlay(image, face_result[1]) # 根据人脸检测网络的识别结果在图像上进行绘制
        image = obj_net.overlay(image, obj_result[1]) # 根据物体检测网络的识别结果在图像上进行绘制

        cv2.imshow("Face/Obj Detector", image)
        cv2.waitKey(1)
finally:
    face_net.quit() # 重置设备,同一个设备退出一个网络即可

关于预处理参数 (scale & mean)

神经网络的输入,根据网络的需要,需要对图像进行预处理操作。

当使用角蜂鸟自带摄像头作为神经网路输入时,目前仅支持对图像的RGB通道进行统一的预处理操作。
这里 角蜂鸟设备内部Python API 都使用 乘加 运算对图像进行预处理操作。

image *= scale
image += mean

若需要图像3通道统一处理,或者对预处理要求不严格,可对mean取均值作为参数输入。

mean = -1.0 # [-1.0, -1.0, -1.0]
scale = 0.007843
graph = device.AllocateGraph(data, scale, mean) # scale & mean
image = graph.GetImage(True) # 自带的设备图像已经过预处理后加载到神经网络中,返回的图像是未处理的原始图像
output, _ = graph.GetResult() # 读取神经网络输出结果

若需要灰度图输入,或者需要对不同的通道进行不同的预处理操作,可对图像自行处理后加载到角蜂鸟中。

image = preprocess(image) # 自行预处理
graph.LoadTensor(image.astype(numpy.float16), None)

API文档

  • hsapi.core
    底层API
    • class Status(enum.Enum)
      返回状态
      • OK 正常
      • BUSY 设备繁忙
      • ERROR 异常
      • OUT_OF_MEMORY 内存溢出
      • DEVICE_NOT_FOUND 没有找到设备
      • INVALID_PARAMETERS 无效的参数
      • TIMEOUT 超时
      • NO_DATA 没有数据
      • GONE 没有找到Graph或已关闭
      • UNSUPPORTED_GRAPH_FILE 不支持的Graph文件
      • MYRIAD_ERROR 内部错误
    • class GlobalOption(enum.Enum)
      全局选项
      • LOG_LEVEL 日志等级
    • GetGlobalOption(opt)
      获取全局选项的值
      • opt 参考GlobalOption
    • SetGlobalOption(opt, data)
      设置全局选项
      • opt 参考GlobalOption
      • data
    • BootUpdateApp(fileName)
      通过Boot模式固件升级,主要用于固件更新失败后的恢复和升级
      • fileName 固件文件
    • EnumerateDevices()
      枚举所有已连接的设备
    • class Device
      设备类
      • init(self, name)
        实例化类对象
      • OpenDevice(self)
        打开设备
      • CloseDevice(self)
        关闭设备
      • UpdateApp(self)
        升级固件
      • AllocateGraph(self, graphfile, std_value=1.0, mean_value=0.0)
        分配神经网络资源,返回Graph实例
        • graphfile graph文件
        • std_value 图像预处理参数
        • mean_value 图像预处理参数
      • GetImage(self, zoomMode=True)
        获取设备图像
        • zoomMode 图像缩放模式 (True: 640x360, False: 1920x1080)
    • class Graph
      神经网络容器类,可由 Device 实例调用 AllocateGraph() 分配获得
      • init(self, handle, std_value, mean_value)
        实例化类对象
        • handle graph句柄
        • std_value 图像预处理参数
        • mean_value 图像预处理参数
      • DeallocateGraph(self)
        释放分配的神经网络资源
      • LoadTensor(self, tensor, userobj)
        加载神经网络输入的图像数据
        • tensor 预处理后的图像数据,格式必须为一个半精度浮点(float16)数类型的 numpy ndarray
        • userobj 自定义参数
      • GetResult(self)
        获取神经网络前向推断的输出结果
      • GetImage(self, zoomMode=True)
        使用自带的摄像头作为神经网络输入,返回输入的图像
        • zoomMode 图像缩放模式 (True: 640x360, False: 1920x1080)
  • hsapi.high
    高层API
    • GetDevice(index=0)
      获取已连接的设备
    • class Net(object)
      神经网络抽象类,该类对Device类和Graph类进行了一些简单的封装
      • scale(self)
        图像预处理参数 (子类必须实现的抽象属性)
      • mean(self)
        图像预处理参数 (子类必须实现的抽象属性)
      • netSize(self)
        神经网络输入的图像大小 (子类必须实现的抽象属性)
      • graphPath(self)
        graph文件路径 (子类必须实现的抽象属性)
      • cleanup(self)
        释放神经网络资源
      • quit(self)
        释放资源并关闭设备
      • run(self, image=None, **kwargs)
        执行一次神经网络
        • image 输入的图像,None则表示使用设备摄像头
    • class SingleTask
      本类管理了两个子线程来执行单一的神经网络任务
      • init(self, net, **kwargs)
        实例化方法
        • net Net实例
      • start(self)
        开始任务
      • stop(self)
        结束任务
  • hsapi.easy
    使用内置神经网络的一些比较方便的API
    • GetDefaultGraphRelPath(fileName)
      获取graphs默认路径
    • GetDefaultMiscRelPath(fileName)
      获取misc默认路径
    • class SSD(object)
      预置的MobileNet-SSD抽象类
      • labels(self)
        分类的标签 (子类必须实现的抽象属性)
      • thresh(self) 分类的阈值 (子类必须实现的抽象属性)
      • getBoundingBoxes(self, output, image_size)
        从神经网络的输出的结果中解析位置信息
        • output 神经网络输出
        • image_size 图像大小
      • overlay(self, image, boxes)
        在图像上叠加位置信息
        • image 图像
        • boxes 位置信息
      • plot(self, result)
        根据输出结果在图像上叠加位置信息
        • result 输出结果
      • crop(self, result, square=True)
        根据输出结果裁剪出识别的图像
        • result 输出结果
        • square 正方形
    • class ObjectDetector(Net, SSD)
      预置模型 - 基于SSD的物体检测
    • class FaceDetector(Net, SSD)
      预置模型 - 基于SSD的人脸检测
    • class FaceDetectorPlus(Net, SSD)
      预置模型 - 基于SSD的人脸检测+
    • class Mnist(Net)
      预置模型 - Mnist
    • class GoogleNet(Net)
      预置模型 - GoogleNet
    • class SceneRecorder(GoogleNet)
      预置模型 - 基于GoogleNet的情景记录器
      • record(self, result, key, **kwargs)
        根据GoogleNet输出结果进行ANN检索,返回相似度结果
        • result GoogleNet输出结果
        • key 指令
    • class SketchGuess(Net)
      预置模型 - 简笔画识别