HLS第二课（xfopencv Mat）

xfopencv API Reference：
https://www.xilinx.com/html_docs/xilinx2017_1/sdsoc_doc/topics/xfopencv-overview/c-xfopencv-overview.html

++++++++++++++++++++++++++++++++++++++++++++++++++++
xf::Mat是一个模板类，用作存储图像数据及其属性的容器。
xf::Mat图像容器类类似于OpenCV库的cv::Mat类。

xf::Mat不能是局部变量。
read+write型的xf::Mat不能是SEQUENTIAL(FIFO)

+++++++++++++++++++++++++++++++++++++++++++++++++

与C环境相关的头文件，例如：
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>

与HLS相关的头文件，需要包含HLS的include的path，
需要包含的文件，例如：
#include “hls_stream.h”
#include “ap_int.h”

需要制定安装的xfopencv的include的path,
例如：
/home/XXX/HLS2019.1/myxfopencv/xfOpenCV/include/
与xfopencv相关的头文件就在这里，例如：

#include “common/xf_common.h”
#include “common/xf_utility.h”
#include “common/xf_infra.h”

等等。

与图像处理相关的头文件，例如：

#include “imgproc/xf_dilation.hpp”
#include “imgproc/xf_erosion.hpp”
#include “imgproc/xf_threshold.hpp”
#include “imgproc/xf_crop.hpp”
#include “imgproc/xf_resize.hpp”
等等。

在CSIM中的tb中包含的H文件，例如：
#include “opencv2/opencv.hpp”
#include “opencv2/imgproc/imgproc.hpp”
#include “opencv2/highgui/highgui.hpp”

#include “common/xf_axi.h”
#include “common/xf_sw_utils.h”

在tb的CPP文件中，要使用CV的命名空间。
using namespace cv;

+++++++++++++++++++++++++++++++++++++++++++++++++++
在自己的H文件中，需要定义一些自己使用的宏。
例如；
在xf_common_params.h中，

#define IN_TYPE XF_8UC1
#define OUT_TYPE XF_16UC1

#define BAYER_WIDTH     6400
#define BAYER_HEIGHT    4852

#define BAYER_BPP      	8

#define BAYER_TYPE      XF_8UC1
#define BAYER_NPPC      XF_NPPC16

Opencv 中CV_8UC1,CV_32FC3等参数的含义
示例： CV_ <bit_depth>(S|U|F)C<number_of_channels>

1） --bit_depth—比特数—代表8bite,16bites,32bites,64bites—举个例子吧–比如说,如
如果你现在创建了一个存储–灰度图片的Mat对象,这个图像的大小为宽100,高100,那么,现在这张灰度图片中有10000个像素点，它每一个像素点在内存空间所占的空间大小是8bite,8位–所以它对应的就是CV_8

2） --S|U|F–S--代表—signed int—有符号整形
U–代表–unsigned int–无符号整形
F–代表–float---------单精度浮点型

3） --C<number_of_channels>----代表—一张图片的通道数,比如:
1–灰度图片–grayImg—是–单通道图像
2–二值图像，2通道图像，用于图像压缩，傅里叶变化
3–RGB彩色图像---------是–3通道图像
4–带Alph通道的RGB图像–是--4通道图像

在xfopencv中，将前缀CV修改为XF。

XF_NPPC<N>是定义一个时钟周期，并行输入多少个像素进入模块去处理。
通常有XF_NPPC1，XF_NPPC8，XF_NPPC16。

BPP用来定义像素深度。
例如，一幅彩色图像的每个像素用R，G，B三个分量表示，若每个分量用8位，那么一个像素共用24位表示，就说像素的深度为24。

++++++++++++++++++++++++++++++++++++++++++++++++++
xf::Mat模板类定义

template<int T, int ROWS, int COLS, int NPC>
class Mat {
  public:
    int rows, cols, size;                   // actual image size
    DATATYPE *data;

    Mat();                                  // default constructor
    Mat(Size _sz);
    Mat(int _rows, int _cols);
    Mat(int _size, int _rows, int _cols);
    Mat(int _rows, int _cols, void *_data);
    Mat(const Mat&);                        // copy constructor

    Mat& operator= (const Mat&);            // Assignment operator
    XF_TNAME(T,NPC) read(int index);
    float read_float(int index);
    void write(int index, XF_TNAME(T,NPC) val);
    void write_float(int index, float val);

    void init (int _rows, int _cols, bool allocate=true);
    void copyTo (void* fromData);
    unsigned char* copyFrom ();

    const int type() const;
    const int depth() const;
    const int channels() const;

    template<int DST_T>
    void convertTo (Mat<DST_T, ROWS, COLS, NPC> &dst, int otype, double alpha=1, double beta=0);
}；

rows
----像中的行数或图像的高度
cols
----图像中的列数或图像的宽度。
size
----该值使用rows*cols/(number of pixels packed per word).
*data
----class parameters and the pointer to the words that store the pixels of the image.

常用的成员函数；
Mat(int _rows, int _cols)
----This constructor initializes the Mat object using arguments _rows and _cols.

convertTo(Mat <DST_T,ROWS, COLS, NPC> &dst, int otype, double alpha=1, double beta=0)
-----The xf::cv::convertTo function performs bit depth conversion on each individual pixel of the given input image. This method converts the source pixel values to the target data type with appropriate casting.

copyTo(* fromData)
----Copies the data from Data pointer into physically contiguous memory allocated inside the constructor.

copyFrom()
----Returns the pointer to the first location of the *data member.

read(int index)
----Readout a value from a given location and return it as a packed (for multi-pixel/clock) value.

write(int index, XF_TNAME(T,NP C) val)
----Writes a packed (for multi-pixel/clock) value into the given location.

depth()
----Returns the depth of the image

channels()
----Returns number of channels of the image

xf::Mat类的模板参数用于设置像素的深度、图像中的通道数、每个单词的像素填充数、图像的最大行数和列数。
Type
----Type of the pixel data. For example, XF_8UC1 stands for 8-bit unsigned and one channel pixel. More types can be found in include/common/xf_params.h.
HEIGHT
----Maximum height of an image.
WIDTH
----Maximum width of an image.
NPC
----The number of pixels to be packed per word. For instance, XF_NPPC1 for 1 pixel per word; and XF_NPPC8 for 8 pixels per word.

根据每个时钟周期要处理的像素数和类型参数，可能存在不同的数据类型。xfOpenCV库将这些数据类型用于内部处理和xf::Mat类内部。以下是一些受支持的类型:

XF_TNAME(TYPE,NPPC)解析为xf::Mat对象的数据成员的数据类型。
例如，XF_TNAME(XF_8UC1,XF_NPPC8)解析为ap_uint <64>。
Word width字宽=像素深度 x 通道数 x 每个周期要处理的像素数(NPPC)。
XF_DTUNAME(TYPE,NPPC)解析为像素的数据类型。
例如，XF_DTUNAME(XF_32FC1,XF_NPPC1)解析为浮点。
XF_PTSNAME(TYPE,NPPC)解析为像素的“C”数据类型。
例如，XF_PTSNAME (XF_16UC1,XF_NPPC2)解析为无符号短格式。

数据类型的不同取决于像素的深度和图像中通道的数量的组合。
XF_<Number of bits per pixel><signed (S) or unsigned (U) or float (F)>C<number of channels>
例如，对于8位像素无符号1通道，数据类型是XF_8UC1。

+++++++++++++++++++++++++++++++++++++++++
在实时应用中，如果视频是流式的，建议帧缓冲区的位置为xf::Mat，使用库函数处理。

函数xf::imread从指定的文件路径加载图像，复制到xf::Mat并返回它。
注意：在Cosim之类的HLS独立模式下，使用cv::imread，然后使用copyTo函数，而不是xf::imread.

template<int PTYPE, int ROWS, int COLS, int NPC>
xf::Mat<PTYPE, ROWS, COLS, NPC> imread (char *filename, int type)

PTYPE，是输入像素类型。支持的类型有:XF_8UC1、XF_16UC1、XF_8UC4和XF_16UC4。
NPC，是每个周期要处理的像素数;可能的选项是XF_NPPC1和XF_NPPC8。
type，0表示gray，1表示color。

函数xf::imwrite将图像从给定的xf::Mat保存到指定的文件中。图像格式是根据文件扩展名选择的。这个函数内部使用cv::imwrite进行处理。因此，cv::imwrite的所有限制也适用于xf::imwrite。

template <int PTYPE, int ROWS, int COLS, int NPC>
void imwrite(const char *img_name, xf::Mat<PTYPE, ROWS, COLS, NPC> &img)

PTYPE，是输入像素类型。支持的类型有:XF_8UC1、XF_16UC1、XF_8UC4和XF_16UC4。
NPC，是每个周期要处理的像素数;可能的选项是XF_NPPC1和XF_NPPC8。
img_name是具有扩展名的文件名称。
img是要保存的xf::Mat数组。

xf::convertTo函数对给定输入图像的每个像素执行位深度转换。此方法使用适当的类型转换将源像素值转换为目标数据类型。
注意:输出和输入Mat不能相同。也就是说，转换后的图像不能存储在输入图像的Mat中。

template void convertTo(xf::Mat<DST_T,ROWS, COLS, NPC> &dst, int ctype, double alpha=1, double beta=0)

函数xf::absDiff计算xf::Mat和cv::Mat的每个像素之间的绝对差异，并返回cv::Mat中的差异值。

template <int PTYPE, int ROWS, int COLS, int NPC>
void absDiff(cv::Mat &cv_img, xf::Mat<PTYPE, ROWS, COLS, NPC>& xf_img, cv::Mat &diff_img )