Class Definition - 2023.2 English

Vitis Libraries

Release Date
2023-12-20
Version
2023.2 English
template <int T, int ROWS, int COLS, int NPC, int XFCVDEPTH = _XFCVDEPTH_DEFAULT>
class Mat {
   public:
   unsigned char allocatedFlag; // flag to mark memory allocation in this class
   int rows, cols, size;        // actual image size

   typedef XF_TNAME(T, NPC) DATATYPE;
   using _DATATTYPE = typename std::conditional<
      (XFCVDEPTH < 0),
      DATATYPE*,                 // Case of Memory Mapped pointer
      typename std::conditional< // Case of Stream
         (XFCVDEPTH == 0),
         hls::stream<DATATYPE>,           // Case of default Dtream depth or user can override outside
         hls::stream<DATATYPE, XFCVDEPTH> // Case of Stream depth specified
         >::type>::type;
   _DATATTYPE 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();

   Mat& operator=(const Mat&); // Assignment operator

   template <int D = XFCVDEPTH, typename std::enable_if<(D < 0)>::type* = nullptr>
   void alloc_data() {
#ifndef __SYNTHESIS__
      data = (DATATYPE*)malloc(size * sizeof(DATATYPE));

      if (data == NULL) {
         fprintf(stderr, "\nFailed to allocate memory\n");
      } else {
         allocatedFlag = 1;
      }
#endif
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D >= 0)>::type* = nullptr>
   void alloc_data() {
      // This is a stream
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D < 0)>::type* = nullptr>
   void free_data() {
      if (data != NULL) {
#ifndef __SYNTHESIS__
         free(data);
#endif
      }
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D >= 0)>::type* = nullptr>
   void free_data() {}

   template <int D = XFCVDEPTH, typename std::enable_if<(D < 0)>::type* = nullptr>
   void copyData(const Mat& src) {
      for (int i = 0; i < (rows * ((cols + NPC - 1) >> XF_BITSHIFT(NPC))); ++i) {
         data[i] = src.data[i];
      }
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D >= 0)>::type* = nullptr>
   void copyData(const Mat& src) {
      // This is a stream
      assert(0);
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D < 0)>::type* = nullptr>
   void assignDataPtr(void* _data) {
      data = (DATATYPE*)_data;
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D >= 0)>::type* = nullptr>
   void assignDataPtr(void* _data) {
      // This is a stream
      assert(0);
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D < 0)>::type* = nullptr>
   XF_TNAME(T, NPC)
   read(int index) {
      return data[index];
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D >= 0)>::type* = nullptr>
   XF_TNAME(T, NPC)
   read(int index) {
      return data.read();
   }
   float read_float(int index);

   template <int D = XFCVDEPTH, typename std::enable_if<(D < 0)>::type* = nullptr>
   void write(int index, XF_TNAME(T, NPC) val) {
      data[index] = val;
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D >= 0)>::type* = nullptr>
   void write(int index, XF_TNAME(T, NPC) val) {
      data.write(val);
   }
   void write_float(int index, float val);

   template <int D = XFCVDEPTH, typename std::enable_if<(D >= 0)>::type* = nullptr>
   void init(int _rows, int _cols, void* _data) {
      init(_rows, _cols);
      copyTo(_data);
   }

   template <int D = XFCVDEPTH, typename std::enable_if<(D < 0)>::type* = nullptr>
   void init(int _rows, int _cols, void* _data) {
      init(_rows, _cols, false);
      assignDataPtr(_data);
   }

   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, XFCVDEPTH>& dst, int otype, double alpha = 1, double beta = 0);
};

Parameter Descriptions

The following table lists the xf::cv::Mat class parameters and their descriptions:

Table 258 Table xf::cv::Mat Class Parameter Descriptions
Parameter Description
rows The number of rows in the image or height of the image.
cols The number of columns in the image or width of the image.
size The number of words stored in the data member. The value is calculated using 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.

The following table lists the member functions and their descriptions:

Table 259 Table xf::cv::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::cv::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) Refer to xf::cv::convertTo
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.

Template parameters of the xf::cv::Mat class are used to set the depth of the pixel, number of channels in the image, number of pixels packed per word, maximum number of rows and columns of the image. The following table lists the template parameters and their descriptions:

Table 260 Table xf::cv::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.
XFCVDEPTH Depth of the hls::stream in the xf::cv::Mat

Important

All the functions in the library are implemented in streaming model except 7. Bounding box, Canny, Cornertracker, Crop, EdgeTracing, MeanShiftTracking, Rotate are memory mapped implemenations. These functions need to have the flag __SDA_MEM_MAP__ set for compiling correctly

Important

Depth of the image mentioned in the API parameter description tables represents the depth of the hls::stream defined inside the xf::cv::Mat

Important

Default depth value for all the memory mapped implemenations(Bounding box, Canny, Cornertracker, Crop, EdgeTracing, MeanShiftTracking, Rotate) is “_XFCVDEPTH_DEFAULT = -1”. Default depth value for all the streaming model implemenations is “_XFCVDEPTH_DEFAULT = 2”.