xf::Mat 图像容器类

VITIS VISION LIBRARY API REFERENCE
xf::Mat Image Container Class

为了便于在FPGA设备上分配本地存储器，模板中提供了带有编译时参数的xfOpenCV库函数。 数据从cv :: Mat显式复制到xf :: Mat，并存储在物理上连续的内存中，以实现最佳性能。 处理后，xf :: Mat中的输出被复制回cv :: Mat以将其写入内存。
xf::Mat是一个模板类，用作存储图像数据及其属性的容器。
xf::Mat图像容器类类似于OpenCV库的cv::Mat类。

类定义

template<int T, int ROWS, int COLS, int NPC>
class Mat {

  public:
    unsigned char allocatedFlag;            // flag to mark memory allocation in this class
    int rows, cols, size;                   // actual image size

#ifdef __SDSVHLS__
    typedef XF_TNAME(T,NPC) DATATYPE;
#else                                       // When not being built for V-HLS
    typedef struct {
        XF_CTUNAME(T,NPC) chnl[XF_NPIXPERCYCLE(NPC)][XF_CHANNELS(T,NPC)];
    } __attribute__ ((packed)) DATATYPE;
#endif

//#if (defined  (__SDSCC__) ) || (defined (__SYNTHESIS__))
#if defined (__SYNTHESIS__) && !defined (__SDA_MEM_MAP__)
    DATATYPE *data __attribute((xcl_array_geometry((ROWS)*(COLS>> (XF_BITSHIFT(NPC))))));//data[ ROWS * ( COLS >> ( XF_BITSHIFT ( NPC ) ) ) ];
#else
    DATATYPE *data;
#endif


    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();

    Mat& operator= (const Mat&);            // Assignment operator
//  XF_TNAME(T, XF_NPPC1) operator() (unsigned int r, unsigned int c);
//  XF_CTUNAME(T, NPC) operator() (unsigned int r, unsigned int c, unsigned int ch);
    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);
};

参数说明

Table xf::Mat Class Parameter Descriptions

Parameter	Description
rows	像中的行数或图像的高度
cols	图像中的列数或图像的宽度。
size	存储在数据成员中的单词数。该值使用rows*cols/(number of pixels packed per word).
allocatedFlag	Flag for memory allocation status
*data	class parameters and the pointer to the words that store the pixels of the image.

成员函数及其描述

https://xilinx.github.io/Vitis_Libraries/vision/api-reference.html#class-definition
Table xf::Mat Member Function Descriptions

Member Functions	Description
Mat()	This default constructor initializes the Mat object sizes, using the template parameters ROWS and COLS.
Mat(int _rows, int _cols)	This constructor initializes the Mat object using arguments _rows and _cols.
Mat(const xf::Mat &_src)	This constructor helps clone a Mat object to another. New memory will be allocated for the newly created constructor.
Mat(int _rows, int _cols, void *_data)	This constructor initializes the Mat object using arguments _rows, _cols, and _data. The *data member of the Mat object points to the memory allocated for _data argument, when this constructor is used. No new memory is allocated for the *data member.
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.
read_float(in t index)	Readout a value from a given location and return it as a float value
write(int index, XF_TNAME(T,NP C) val)	Writes a packed (for multi-pixel/clock) value into the given location.
write_float(i nt index, float val)	Writes a float value into the given location.
type()	Returns the type of the image.
depth()	Returns the depth of the image
channels()	Returns number of channels of the image
~Mat()	This is a default destructor of the Mat object.

xf::Mat类的模板参数用于设置像素的深度、图像中的通道数、每个单词的像素填充数、图像的最大行数和列数。下表列出了模板参数及其描述:

Table xf::Mat Template Parameter Descriptions

Parameters	Description
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函数中实现的并行度保持为可配置的参数。在大多数函数中，有两个处理数据的选项。
单像素处理
并行处理8个像素
下表描述了可用于指定特定函数所需的并行度级别的选项:
Option        Description
XF_NPPC1     Process 1 pixel per clock cycle
XF_NPPC2     Process 2 pixels per clock cycle
XF_NPPC4     Process 4 pixels per clock cycle
XF_NPPC8     Process 8 pixels per clock cycle

Macros to Work With Parallelism

There are two macros that are defined to work with parallelism.

• XF_NPIXPERCYCLE(flags)宏解析为每个周期处理的像素数量。
  XF_NPIXPERCYCLE(XF_NPPC1) resolves to 1
  XF_NPIXPERCYCLE(XF_NPPC2) resolves to 2
  XF_NPIXPERCYCLE(XF_NPPC4) resolves to 4
  XF_NPIXPERCYCLE(XF_NPPC8) resolves to 8
• XF_BITSHIFT(flags)宏解析为将图像大小右移的次数，以得到并行处理的最终数据传输大小。
  XF_BITSHIFT(XF_NPPC1) resolves to 0
  XF_BITSHIFT(XF_NPPC2) resolves to 1
  XF_BITSHIFT(XF_NPPC4) resolves to 2
  XF_BITSHIFT(XF_NPPC8) resolves to 3

数据类型

数据类型的不同取决于像素的深度和图像中通道的数量的组合。参数的通用命名法如下所示。

XF_<Number of bits per pixel><signed (S) or unsigned (U) or float (F)>C<number of channels>

例如，对于8位像素无符号1通道，数据类型是XF_8UC1。
下表列出了xf::Mat类的可用数据类型:
Table xf::Mat Class - Available Data Types

Option	像素位数	类型	通道数
XF_8UC1	8	Unsigned	1
XF_16UC1	16	Unsigned	1
XF_16SC1	16	Signed	1
XF_32UC1	32	Unsigned
XF_32FC1	32	Float	1
XF_32SC1	32	Signed	1
XF_8UC3	8	Unsigned	3

XF_8UC2、XF_8UC4、XF_2UC1等

Manipulating Data Type 使用数据类型

根据每个时钟周期要处理的像素数和类型参数，可能存在不同的数据类型。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)解析为无符号短格式。

NOTE：ap_uint<>、ap_int<>、ap_fixed<>和ap_ufixed<>类型属于高级综合(HLS)库。有关更多信息，请参见(UG902)。

例子说明

下面的代码演示了使用Zynq®UltraScale™平台的SDSoC™工具在图像上构建高斯滤波器所需的配置。
注:在实时应用中，如果视频是流式的，建议帧缓冲区的位置为xf::Mat，使用库函数处理。生成的位置指针（ location pointer ）被传递给显示ip。
。。。

xf::imread

函数xf::imread从指定的文件路径加载图像，复制到xf::Mat并返回它。如果无法读取图像(由于缺少文件、不适当的权限、不支持或无效的格式)，函数将使用非零返回代码和错误语句退出。
注意：在Cosim之类的HLS独立模式下，使用cv::imread，然后使用copyTo函数，而不是xf::imread
注意：在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)

xf::imwrite

The function xf::imwrite saves the image to the specified file from the given xf::Mat. The image format is chosen based on the file name extension. This function internally uses cv::imwrite for the processing. Therefore, all the limitations of cv::imwrite are also applicable to xf::imwrite.
函数xf::imwrite将图像从给定的xf::Mat保存到指定的文件中。图像格式是根据文件扩展名选择的。这个函数内部使用cv::imwrite进行处理。因此，cv::imwrite的所有限制也适用于xf::imwrite。
API Syntax
template <int PTYPE, int ROWS, int COLS, int NPC>
void imwrite(const char *img_name, xf::Mat<PTYPE, ROWS, COLS, NPC> &img)

Table xf::imwrite Parameter Description

Parameter	Description
PTYPE	输入像素类型。支持的类型有:XF_8UC1、XF_16UC1、XF_8UC4和XF_16UC4
ROWS	要读取的图像的最大高度
COLS	要读取的图像的最大宽度
NPC	每个周期要处理的像素数;可能的选项是XF_NPPC1和XF_NPPC8
img_name	具有扩展名的文件名称
img	要保存的xf::Mat数组

xf::absDiff

函数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 )

xf::convertTo

xf::convertTo函数对给定输入图像的每个像素执行位深度转换。此方法使用适当的类型转换将源像素值转换为目标数据类型。
注意:输出和输入Mat不能相同。也就是说，转换后的图像不能存储在输入图像的Mat中。
template void convertTo(xf::Mat<DST_T,ROWS, COLS, NPC> &dst, int ctype, double alpha=1, double beta=0)

疑问：

xf::cv::Mat 和 xf::Mat 区别