Mat Class Reference

The Mat class can handle multiple matrix formats from 1 to 4 channels, with different value types (float or uchar), and can be stored CPU and/or GPU side. More...

Functions

 Mat ()
 empty Mat default constructor. More...
 
 Mat (size_t width, size_t height, MAT_TYPE mat_type, MEM memory_type=MEM::CPU)
 Mat constructor. More...
 
 Mat (size_t width, size_t height, MAT_TYPE mat_type, sl::uchar1 *ptr, size_t step, MEM memory_type=MEM::CPU)
 Mat constructor from an existing data pointer. More...
 
 Mat (size_t width, size_t height, MAT_TYPE mat_type, sl::uchar1 *ptr_cpu, size_t step_cpu, sl::uchar1 *ptr_gpu, size_t step_gpu)
 Mat constructor from two existing data pointers, CPU and GPU. More...
 
 Mat (Resolution resolution, MAT_TYPE mat_type, MEM memory_type=MEM::CPU)
 Mat constructor. More...
 
 Mat (Resolution resolution, MAT_TYPE mat_type, sl::uchar1 *ptr, size_t step, MEM memory_type=MEM::CPU)
 Mat constructor from an existing data pointer. More...
 
 Mat (Resolution resolution, MAT_TYPE mat_type, sl::uchar1 *ptr_cpu, size_t step_cpu, sl::uchar1 *ptr_gpu, size_t step_gpu)
 Mat constructor from two existing data pointers, CPU and GPU. More...
 
 Mat (const Mat &mat)
 Mat constructor by copy (shallow copy). More...
 
void alloc (size_t width, size_t height, MAT_TYPE mat_type, MEM memory_type=MEM::CPU)
 Allocates the Mat memory. More...
 
void alloc (Resolution resolution, MAT_TYPE mat_type, MEM memory_type=MEM::CPU)
 Allocates the Mat memory. More...
 
 ~Mat ()
 Mat destructor. This function calls free to release owned memory. More...
 
void free (MEM memory_type=MEM::CPU|MEM::GPU)
 Free the owned memory. More...
 
Matoperator= (const Mat &that)
 Performs a shallow copy. More...
 
ERROR_CODE updateCPUfromGPU (cudaStream_t stream=0)
 Downloads data from DEVICE (GPU) to HOST (CPU), if possible. More...
 
ERROR_CODE updateGPUfromCPU (cudaStream_t stream=0, int GPU_id=0)
 Uploads data from HOST (CPU) to DEVICE (GPU), if possible. More...
 
ERROR_CODE copyTo (Mat &dst, COPY_TYPE cpyType=COPY_TYPE::CPU_CPU, cudaStream_t stream=0) const
 Copies data an other Mat (deep copy). More...
 
ERROR_CODE setFrom (const Mat &src, COPY_TYPE cpyType=COPY_TYPE::CPU_CPU, cudaStream_t stream=0)
 Copies data from an other Mat (deep copy). More...
 
ERROR_CODE read (const String &filePath)
 Reads an image from a file. More...
 
ERROR_CODE write (const String &filePath, sl::MEM memory_type=sl::MEM::CPU, int compression_level=-1)
 Writes the Mat (only if MEM::CPU is available) into a file defined by its extension. More...
 
template<typename T >
ERROR_CODE setTo (T value, sl::MEM memory_type=MEM::CPU)
 Fills the Mat with the given value. More...
 
template<typename N >
ERROR_CODE setValue (size_t x, size_t y, N value, sl::MEM memory_type=MEM::CPU)
 Sets a value to a specific point in the matrix. More...
 
template<typename N >
ERROR_CODE getValue (size_t x, size_t y, N *value, MEM memory_type=MEM::CPU) const
 Returns the value of a specific point in the matrix. More...
 
size_t getWidth () const
 Returns the width of the matrix. More...
 
size_t getHeight () const
 Returns the height of the matrix. More...
 
Resolution getResolution () const
 Returns the resolution (width and height) of the matrix. More...
 
size_t getChannels () const
 Returns the number of values stored in one pixel. More...
 
MAT_TYPE getDataType () const
 Returns the format of the matrix. More...
 
MEM getMemoryType () const
 Returns the type of memory (CPU and/or GPU). More...
 
template<typename N >
N * getPtr (MEM memory_type=MEM::CPU) const
 Returns the CPU or GPU data pointer. More...
 
size_t getStepBytes (MEM memory_type=MEM::CPU) const
 Returns the memory step in Bytes (the Bytes size of one pixel row). More...
 
template<typename N >
size_t getStep (MEM memory_type=MEM::CPU) const
 Returns the memory step in number of elements (the number of values in one pixel row). More...
 
size_t getStep (MEM memory_type=MEM::CPU) const
 Returns the memory step in number of elements (the number of values in one pixel row). More...
 
size_t getPixelBytes () const
 Returns the size in bytes of one pixel. More...
 
size_t getWidthBytes () const
 Returns the size in bytes of a row. More...
 
String getInfos ()
 Returns the information about the Mat into a String. More...
 
bool isInit () const
 Defines whether the Mat is initialized or not. More...
 
bool isMemoryOwner () const
 Returns whether the Mat is the owner of the memory it accesses. More...
 
ERROR_CODE clone (const Mat &src)
 Duplicates Mat by copy (deep copy). More...
 
ERROR_CODE move (Mat &dst)
 Moves Mat data to another Mat. More...
 

Static Functions

static void swap (Mat &mat1, Mat &mat2)
 Swaps the content of the provided Mat (only swaps the pointers, no data copy). More...
 

Attributes

String name = "n/a"
 
bool verbose = false
 
Timestamp timestamp = 0
 

Detailed Description

The Mat class can handle multiple matrix formats from 1 to 4 channels, with different value types (float or uchar), and can be stored CPU and/or GPU side.

Mat is defined in a row-major order, it means that, for an image buffer, the entire first row is stored first, followed by the entire second row, and so on.

The CPU and GPU buffer aren't automatically synchronized for performance reasons, you can use updateCPUfromGPU / updateGPUfromCPU to do it. If you are using the GPU side of the Mat object, you need to make sure to call free before destroying the sl::Camera object. The destruction of the sl::Camera object deletes the CUDA context needed to free the GPU Mat memory.

Constructor and Destructor

◆ Mat() [1/8]

Mat ( )

empty Mat default constructor.

◆ Mat() [2/8]

Mat ( size_t  width,
size_t  height,
MAT_TYPE  mat_type,
MEM  memory_type = MEM::CPU 
)

Mat constructor.

This function directly allocates the requested memory. It calls alloc.

Parameters
width: width of the matrix in pixels.
height: height of the matrix in pixels.
mat_type: the type of the matrix (MAT_TYPE::F32_C1, MAT_TYPE::U8_C4...).
memory_type: defines where the buffer will be stored. (MEM::CPU and/or MEM::GPU).

◆ Mat() [3/8]

Mat ( size_t  width,
size_t  height,
MAT_TYPE  mat_type,
sl::uchar1 ptr,
size_t  step,
MEM  memory_type = MEM::CPU 
)

Mat constructor from an existing data pointer.

This function doesn't allocate the memory.

Parameters
width: width of the matrix in pixels.
height: height of the matrix in pixels.
mat_type: the type of the matrix (MAT_TYPE::F32_C1, MAT_TYPE::U8_C4...).
ptr: pointer to the data array. (CPU or GPU).
step: step of the data array. (the Bytes size of one pixel row).
memory_type: defines where the buffer will be stored. (MEM::CPU and/or MEM::GPU).

◆ Mat() [4/8]

Mat ( size_t  width,
size_t  height,
MAT_TYPE  mat_type,
sl::uchar1 ptr_cpu,
size_t  step_cpu,
sl::uchar1 ptr_gpu,
size_t  step_gpu 
)

Mat constructor from two existing data pointers, CPU and GPU.

This function doesn't allocate the memory.

Parameters
width: width of the matrix in pixels.
height: height of the matrix in pixels.
mat_type: the type of the matrix (MAT_TYPE::F32_C1, MAT_TYPE::U8_C4...).
ptr_cpu: CPU pointer to the data array.
step_cpu: step of the CPU data array (the Bytes size of one pixel row).
ptr_gpu: GPU pointer to the data array.
step_gpu: step of the GPU data array (the Bytes size of one pixel row).

◆ Mat() [5/8]

Mat ( Resolution  resolution,
MAT_TYPE  mat_type,
MEM  memory_type = MEM::CPU 
)

Mat constructor.

This function directly allocates the requested memory. It calls alloc.

Parameters
resolution: the size of the matrix in pixels.
mat_type: the type of the matrix (MAT_TYPE::F32_C1, MAT_TYPE::U8_C4...).
memory_type: defines where the buffer will be stored (MEM::CPU and/or MEM::GPU).

◆ Mat() [6/8]

Mat ( Resolution  resolution,
MAT_TYPE  mat_type,
sl::uchar1 ptr,
size_t  step,
MEM  memory_type = MEM::CPU 
)

Mat constructor from an existing data pointer.

This function doesn't allocate the memory.

Parameters
resolution: the size of the matrix in pixels.
mat_type: the type of the matrix (MAT_TYPE::F32_C1, MAT_TYPE::U8_C4...).
ptr: pointer to the data array. (CPU or GPU).
step: step of the data array (the Bytes size of one pixel row).
memory_type: defines where the buffer will be stored. (MEM::CPU and/or MEM::GPU).

◆ Mat() [7/8]

Mat ( Resolution  resolution,
MAT_TYPE  mat_type,
sl::uchar1 ptr_cpu,
size_t  step_cpu,
sl::uchar1 ptr_gpu,
size_t  step_gpu 
)

Mat constructor from two existing data pointers, CPU and GPU.

This function doesn't allocate the memory.

Parameters
resolution: the size of the matrix in pixels.
mat_type: the type of the matrix (MAT_TYPE::F32_C1, MAT_TYPE::U8_C4...).
ptr_cpu: CPU pointer to the data array.
step_cpu: step of the CPU data array (the Bytes size of one pixel row).
ptr_gpu: GPU pointer to the data array.
step_gpu: step of the GPU data array (the Bytes size of one pixel row).

◆ Mat() [8/8]

Mat ( const Mat mat)

Mat constructor by copy (shallow copy).

This function doesn't allocate the memory.

Parameters
mat: the reference to the Mat to copy.

◆ ~Mat()

~Mat ( )

Mat destructor. This function calls free to release owned memory.

Functions

◆ alloc() [1/2]

void alloc ( size_t  width,
size_t  height,
MAT_TYPE  mat_type,
MEM  memory_type = MEM::CPU 
)

Allocates the Mat memory.

Parameters
width: width of the matrix in pixels.
height: height of the matrix in pixels.
mat_type: the type of the matrix (MAT_TYPE::F32_C1, MAT_TYPE::U8_C4...).
memory_type: defines where the buffer will be stored. (MEM::CPU and/or MEM::GPU).
Warning
It erases previously allocated memory.

◆ alloc() [2/2]

void alloc ( Resolution  resolution,
MAT_TYPE  mat_type,
MEM  memory_type = MEM::CPU 
)

Allocates the Mat memory.

Parameters
resolution: the size of the matrix in pixels.
mat_type: the type of the matrix (sl::MAT_TYPE::F32_C1,sl::MAT_TYPE::U8_C4...).
memory_type: defines where the buffer will be stored. (sl::MEM::CPU and/or sl::MEM::GPU).
Warning
It erases previously allocated memory.

◆ free()

void free ( MEM  memory_type = MEM::CPU|MEM::GPU)

Free the owned memory.

Parameters
memory_type: specifies whether you want to free the MEM::CPU and/or MEM::GPU memory.

◆ operator=()

Mat& operator= ( const Mat that)

Performs a shallow copy.

This function doesn't copy the data array, it only copies the pointer.

Parameters
that: the Mat to be copied.
Returns
The new Mat object which point to the same data as that.

◆ updateCPUfromGPU()

ERROR_CODE updateCPUfromGPU ( cudaStream_t  stream = 0)

Downloads data from DEVICE (GPU) to HOST (CPU), if possible.

Parameters
stream: specifies the GPU stream to be used to enable Asynchronous overlaping (default 0 is synchronous).
Returns
SUCCESS if everything went well, ERROR_CODE::FAILURE otherwise.
Note
If no CPU or GPU memory are available for this Mat, some are directly allocated.
If verbose is set to true, you have information in case of failure.

◆ updateGPUfromCPU()

ERROR_CODE updateGPUfromCPU ( cudaStream_t  stream = 0,
int  GPU_id = 0 
)

Uploads data from HOST (CPU) to DEVICE (GPU), if possible.

Parameters
stream: specifies the GPU stream to be used to enable Asynchronous overlaping (default 0 is synchronous).
Returns
ERROR_CODE::SUCCESS if everything went well, ERROR_CODE::FAILURE otherwise.
Note
If no CPU or GPU memory are available for this Mat, some are directly allocated.
If verbose is set to true, you have information in case of failure.

◆ copyTo()

ERROR_CODE copyTo ( Mat dst,
COPY_TYPE  cpyType = COPY_TYPE::CPU_CPU,
cudaStream_t  stream = 0 
) const

Copies data an other Mat (deep copy).

Parameters
dst: the Mat where the data will be copied.
cpyType: specifies the memories that will be used for the copy.
stream: specifies the GPU stream to be used to enable Asynchronous overlaping (default 0 is synchronous).
Returns
ERROR_CODE::SUCCESS if everything went well, ERROR_CODE::FAILURE otherwise.
Note
If the destination is not allocated or or doesn't have a compatible MAT_TYPE or Resolution, current memory is freed and new memory is directly allocated.

◆ setFrom()

ERROR_CODE setFrom ( const Mat src,
COPY_TYPE  cpyType = COPY_TYPE::CPU_CPU,
cudaStream_t  stream = 0 
)

Copies data from an other Mat (deep copy).

Parameters
src: the Mat where the data will be copied from.
cpyType: specifies the memories that will be used for the update.
stream: specifies the GPU stream to be used to enable Asynchronous overlaping (default 0 is synchronous).
Returns
ERROR_CODE::SUCCESS if everything went well, ERROR_CODE::FAILURE otherwise.
Note
If the current Mat is not allocated or doesn't have a compatible MAT_TYPE or Resolution with the source, current memory is freed and new memory is directly allocated.

◆ read()

ERROR_CODE read ( const String filePath)

Reads an image from a file.

Parameters
filePath: file path including the name and extension.
Returns
ERROR_CODE::SUCCESS if everything went well, ERROR_CODE::FAILURE otherwise.
Note
This function only support images such as JPG or PNG, and can't load float format such as PCD, PLY, etc

◆ write()

ERROR_CODE write ( const String filePath,
sl::MEM  memory_type = sl::MEM::CPU,
int  compression_level = -1 
)

Writes the Mat (only if MEM::CPU is available) into a file defined by its extension.

Parameters
filePath: file path including the name and extension.
memory_type: memory type (CPU or GPU) of the Mat.
compression_level: level of compression between 0 (lowest compression == highest size == highest quality(jpg)) and 100 (highest compression == lowest size == lowest quality(jpg)).
Note
Specific/default value for compression_level = -1 : This will set the default quality for PNG(30) or JPEG(5).
compression_level is only supported for U8_Cx MAT_TYPE.
Returns
ERROR_CODE::SUCCESS if everything went well, ERROR_CODE::FAILURE otherwise.
Note
Supported MAT_TYPE are : MAT_TYPE::F32_C1 for PNG/PFM/PGM, MAT_TYPE::F32_C3 for PCD/PLY/VTK/XYZ, MAT_TYPE::F32_C4 for PCD/PLY/VTK/WYZ, MAT_TYPE::U8_C1 for PNG/JPG, MAT_TYPE::U8_C3 for PNG/JPG, MAT_TYPE::U8_C4 for PNG/JPG,

◆ setTo()

ERROR_CODE setTo ( value,
sl::MEM  memory_type = MEM::CPU 
)

Fills the Mat with the given value.

This function overwrites all the matrix.

Parameters
value: the value to be copied all over the matrix.
memory_type: defines which buffer to fill, CPU and/or GPU.
Note
This function is templated for uchar1, uchar2, uchar3, uchar4, float1, float2, float3, float4.

◆ setValue()

ERROR_CODE setValue ( size_t  x,
size_t  y,
value,
sl::MEM  memory_type = MEM::CPU 
)

Sets a value to a specific point in the matrix.

Parameters
x: specifies the column.
y: specifies the row.
value: the value to be set.
memory_type: defines which memory will be updated.
Returns
ERROR_CODE::SUCCESS if everything went well, ERROR_CODE::FAILURE otherwise.
Note
This function is templated for uchar1, uchar2, uchar3, uchar4, float1, float2, float3, float4.
Warning
Not efficient for MEM::GPU, use it on sparse data.

◆ getValue()

ERROR_CODE getValue ( size_t  x,
size_t  y,
N *  value,
MEM  memory_type = MEM::CPU 
) const

Returns the value of a specific point in the matrix.

Parameters
x: specifies the column
y: specifies the row
memory_type: defines which memory should be read.
Returns
ERROR_CODE::SUCCESS if everything went well, ERROR_CODE::FAILURE otherwise.
Note
This function is templated for uchar1, uchar2, uchar3, uchar4, float1, float2, float3, float4.
Warning
Not efficient for MEM::GPU, use it on sparse data.

◆ getWidth()

size_t getWidth ( ) const
inline

Returns the width of the matrix.

Returns
The width of the matrix in pixels.

◆ getHeight()

size_t getHeight ( ) const
inline

Returns the height of the matrix.

Returns
The height of the matrix in pixels.

◆ getResolution()

Resolution getResolution ( ) const
inline

Returns the resolution (width and height) of the matrix.

Returns
The resolution of the matrix in pixels.

◆ getChannels()

size_t getChannels ( ) const
inline

Returns the number of values stored in one pixel.

Returns
The number of values in a pixel.

◆ getDataType()

MAT_TYPE getDataType ( ) const
inline

Returns the format of the matrix.

Returns
The format of the current Mat.

◆ getMemoryType()

MEM getMemoryType ( ) const
inline

Returns the type of memory (CPU and/or GPU).

Returns
The type of allocated memory.

◆ getPtr()

N* getPtr ( MEM  memory_type = MEM::CPU) const

Returns the CPU or GPU data pointer.

Parameters
memory_type: specifies whether you want MEM::CPU or MEM::GPU step.
Returns
The pointer of the Mat data.

◆ getStepBytes()

size_t getStepBytes ( MEM  memory_type = MEM::CPU) const

Returns the memory step in Bytes (the Bytes size of one pixel row).

Parameters
memory_type: specifies whether you want MEM::CPU or MEM::GPU step.
Returns
The step in bytes of the specified memory.

◆ getStep() [1/2]

size_t getStep ( MEM  memory_type = MEM::CPU) const
inline

Returns the memory step in number of elements (the number of values in one pixel row).

Parameters
memory_type: specifies whether you want MEM::CPU or MEM::GPU step.
Returns
The step in number of elements.

◆ getStep() [2/2]

size_t getStep ( MEM  memory_type = MEM::CPU) const
inline

Returns the memory step in number of elements (the number of values in one pixel row).

Parameters
memory_type: specifies whether you want MEM::CPU or MEM::GPU step.
Returns
The step in number of elements.

◆ getPixelBytes()

size_t getPixelBytes ( ) const
inline

Returns the size in bytes of one pixel.

Returns
The size in bytes of a pixel.

◆ getWidthBytes()

size_t getWidthBytes ( ) const
inline

Returns the size in bytes of a row.

Returns
The size in bytes of a row.

◆ getInfos()

String getInfos ( )

Returns the information about the Mat into a String.

Returns
A string containing the Mat information.

◆ isInit()

bool isInit ( ) const
inline

Defines whether the Mat is initialized or not.

Returns
True if current Mat has been allocated (by the constructor or therefore).

◆ isMemoryOwner()

bool isMemoryOwner ( ) const
inline

Returns whether the Mat is the owner of the memory it accesses.

If not, the memory won't be freed if the Mat is destroyed.

Returns
True if the Mat is owning its memory, else false.

◆ clone()

ERROR_CODE clone ( const Mat src)

Duplicates Mat by copy (deep copy).

Parameters
src: the reference to the Mat to copy. This function copies the data array(s), it marks the new Mat as the memory owner.

◆ move()

ERROR_CODE move ( Mat dst)

Moves Mat data to another Mat.

This function gives the attribute of the current Mat to the specified one. (No copy).

Parameters
dst: the reference to the Mat to move.
Note
: the current Mat is then no more usable since its loose its attributes.

◆ swap()

static void swap ( Mat mat1,
Mat mat2 
)
static

Swaps the content of the provided Mat (only swaps the pointers, no data copy).

This function swaps the pointers of the given Mat.

Parameters
mat1: the first mat.
mat2: the second mat.

Variables

◆ name

String name = "n/a"

◆ verbose

bool verbose = false

◆ timestamp

Timestamp timestamp = 0