图形运算加速模块

BMCV提供了一套基于算丰AI芯片优化的机器视觉库，目前可以完成色彩空间变换，尺度变换，仿射变换，线性变换等操作。关于bmcv模块详细内容请阅读BMCV_User_Guide.pdf。

​ python接口的实现请参考Sophon_Inference_zh.pdf

​ bmcv api均是围绕bm_image来进行的。一个bm_image结构对应于一张图片。用户通过一系列bm_image_create的API来构建bm_image结构体，然后供各个bmcv的功能函数使用。

1. C语言编程接口

bm_image结构体：

struct bm_image {
    int width;
    int height;
    bm_image_format_ext image_format;
    bm_data_format_ext data_type;
    bm_image_private* image_private;
};

bm_image 结构成员包括图片的宽高，，图片格式，图片数据格式，以及该结构的私有数据。

关于bm_image初始化，我们不建议用户直接填充bm_image结构使用，而是通过以下API来创建/销毁一个bm_image结构

图片格式 image_format枚举类型

typedef enum bm_image_format_ext_{
    FORMAT_YUV420P,
    FORMAT_NV12,
    FORMAT_NV21,
    FORMAT_NV16,
    FORMAT_NV61,
    FORMAT_RGB_PLANAR,
    FORMAT_BGR_PLANAR,
    FORMAT_RGB_PACKED,
    FORMAT_BGR_PACKED,
    FORMAT_GRAY,
    FORMAT_COMPRESSED
}bm_image_format_ext;

格式	说明
FORMAT_YUV420P	表示预创建一个YUV420格式的图片，有三个plane
FORMAT_NV12	表示预创建一个NV12格式的图片，有两个plane
FORMAT_NV21	表示预创建一个NV21格式的图片，有两个plane
FORMAT_RGB_PLANAR	表示预创建一个RGB格式的图片，RGB分开排列，有一个plane
FORMAT_BGR_PLANAR	表示预创建一个BGR格式的图片，BGR分开排列，有一个plane
FORMAT_RGB_PACKED	表示预创建一个RGB格式的图片，RGB交错排列，有一个plane
FORMAT_BGR_PACKED	表示预创建一个BGR格式的图片，BGR交错排列，有一个plane
FORMAT_GRAY	表示预创建一个灰度图格式的图片，有一个plane
FORMAT_COMPRESSED	表示预创建一个VPU内部压缩格式的图片，有四个plane

数据存储格式枚举

typedef enum bm_image_data_format_ext_{
    DATA_TYPE_EXT_FLOAT32,
    DATA_TYPE_EXT_1N_BYTE,
    DATA_TYPE_EXT_4N_BYTE,
    DATA_TYPE_EXT_1N_BYTE_SIGNED,
    DATA_TYPE_EXT_4N_BYTE_SIGNED,
}bm_image_data_format_ext;

数据格式	说明
DATA_TYPE_EXT_FLOAT32	表示所创建的图片数据格式为单精度浮点数
DATA_TYPE_EXT_1N_BYTE	表示所创建图片数据格式为普通带符号1N INT8
DATA_TYPE_EXT_4N_BYTE	表示所创建图片数据格式为4N INT8，即四张带符号INT8图片数据交错排列
DATA_TYPE_EXT_1N_BYTE_SIGNED	表示所创建图片数据格式为普通无符号1N UINT8
DATA_TYPE_EXT_4N_BYTE	表示所创建图片数据格式为4N UINT8，即四张无符号INT8图片数据交错排列

​ 关于bm_image初始化，我们不建议用户直接填充bm_image结构使用，而是通过以下API来创建/销毁一个bm_image结构

• bm_image_create_batch

  创建物理内存连续的多个bm image。

   /*
   * @param [in]     handle       handle of low level device             
   * @param [in]     img_h        image height                 
   * @param [in]     img_w        image width
   * @param [in]     img_format   format of image: BGR or YUV
   * @param [in]     data_type    data type of image: INT8 or FP32 
   * @param [out]    image        pointer of bm image object
   * @param [in]     batch_num    batch size
   */
   static inline bool bm_image_create_batch (bm_handle_t              handle,  
                                            int                      img_h,  
                                          int                      img_w,    
                                            bm_image_format_ext      img_format,
                                          bm_image_data_format_ext data_type,  
                                            bm_image                 *image, 
                                            int                      batch_num)

• bm_image_destroy_batch

  释放物理内存连续的多个bm image。要和bm_image_create_batch接口成对使用。

  /*
  * @param [in]     image        pointer of bm image object
  * @param [in]     batch_num    batch size
  */
  static inline bool bm_image_destroy_batch (bm_image *image, int batch_num)

• bm_image_alloc_contiguous_mem

  为多个 image 分配连续的内存

  bm_status_t bm_image_alloc_contiguous_mem(
                  int image_num,
                  bm_image *images,
                  int bmcv_image_usage
  );

  参数	说明
  int image_num	待分配内存的 image 个数
  bm_image *images	待分配内存的 image 的指针
  int bmcv_image_usage	已经为客户默认设置了参数，（如果客户对于所分配内存位置有要求，可以通过该参数进行制定）

• bm_image_free_contiguous_mem

  释放通过bm_image_alloc_contiguous_mem申请的内存

  bm_status_t bm_image_free_contiguous_mem(
                  int image_num,
                  bm_image *images
          );

  参数	说明
  int image_num	待分配内存的 image 个数
  bm_image *images	待分配内存的 image 的指针

• bmcv_image_vpp_convert

  bm1684上有专门的视频后处理硬件，满足一定条件下可以一次实现csc + crop + resize功能，速度比TPU更快。

  bmcv_image_vpp_convert(
  bm_handle_t           handle,
        int                   output_num,
        bm_image              input,
        bm_image *            output,
        bmcv_rect_t *         crop_rect,
        bmcv_resize_algorithm algorithm = BMCV_INTER_LINEAR);

  该API将输入图像格式转化为输出图像格式，并支持crop + resize功能， 支持从1张输入中crop多张输出并resize到输出图片大小。

  参数	说明
  bm_handle_t handle	设备环境句柄，通过调用bm_dev_request获取
  int image_num	输bm_image数量
  bm_image input	输入bm_image对象
  bm_image* output	输出bm_image对象指针
  bmcv_rect_t * crop_rect	每个输出bm_image对象所对应的在输入图像上crop的参数
  bmcv_resize_algorithm algorithm = BMCV_INTER_LINEAR)	resize算法选择，默认情况下是双线性差值

• bmcv_convert_to

  实现图像像素线性变化，具体数据关系可用公式表示

  $$y= α*x+ β$$

  bm_status_t bmcv_convert_to (bm_handle_t handle,int input_num,
                          bmcv_convert_to_attr convert_to_attr, 
                          bm_image* input, bm_image* output)

  参数	说明
  bm_handle_thandle	输入的bm_handle句柄
  int input_num	输入图片数。最多支持4
  bmcv_convert_to_attr convert_to_attr	每张图片对应的配置参数
  bm_image* input	输入bm_image。每个bm_image外部需要调用bmcv_image_create创建。image内存可以使用bmcv_image_dev_mem_alloc或者bmcv_image_copy_to_device来开辟新的内存，或者使用bmcv_image_attach来attach已有的内存。
  bm_image*output	输出bm_image。每个bm_image外部需要调用bmcv_image_create创建。image内存可以通过bmcv_image_dev_mem_alloc来开辟新的内存，或者使用bmcv_image_attach来attach已有的内存。如果不主动分配将在api内部进行自行分配

  结构体bmcv_convert_to_attr_s

  typedef struct bmcv_convert_to_attr_s {
      float alpha_0;                 
      float beta_0;  
      float alpha_1;
      float beta_1;
      float alpha_2;
      float beta_2;
  } bmcv_convert_to_attr;

  参数	说明
  alpha_0	描述了第0个channel进行线性变换的系数
  beta_0	描述了第0个channel进行线性变换的偏移
  alpha_1	描述了第1个channel进行线性变换的系数
  beta_1	描述了第1个channel进行线性变换的偏移
  alpha_2	描述了第2个channel进行线性变换的系数
  beta_2	描述了第2个channel进行线性变换的偏移

  结构体描述了三通道中的alpha和beta。实际要根据推理的输入数据是几通道来进行参数配置。

2. python语言编程接口

本章节只介绍了用例py_ffmpeg_bmcv_sail中用的的接口函数

更多接口定义请查阅Sophon_Inference_zh.pdf

• init

  def __init__(handle): 
  """ Constructor.
  Parameters 
  ---------
  handle : sail.Handle Handle instance 
  """

• tensor_to_bm_image

  def tensor_to_bm_image(tensor): 
  """ Convert tensor to image.
  Parameters 
  ---------
  tensor : sail.Tensor Tensor instance
  Returns 
  ------
  image : sail.BMImage BMImage instance 
  """

• convert_to

  def convert_to(input, alpha_beta): 
  """ Applies a linear transformation to an image.
  Parameters
  ---------
  input : sail.BMImage Input image 
  alpha_beta: tuple (a0, b0), (a1, b1), (a2, b2) factors
  Returns 
  ---------
  output : sail.BMImage Output image 
  """

• vpp_resize

  def vpp_resize(input, resize_w, resize_h): 
  """ Resize an image with interpolation of INTER_NEAREST using vpp.
  Parameters 
  ---------
  input : sail.BMImage Input image 
  resize_w : int Target width 
  resize_h : int Target height
  Returns 
  ---------
  output : sail.BMImage Output image 
  """