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

General 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...

Mat &	operator= (const Mat &that)
	Performs a shallow copy. More...

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

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

ERROR_CODE	copyTo (Mat &dst, COPY_TYPE cpyType=COPY_TYPE_CPU_CPU) 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 (only if MEM_CPU is available on the current Mat). More...

ERROR_CODE	write (const String &filePath)
	Writes the Mat (only if MEM_CPU is available) into a file as an image. More...

template<typename T >
ERROR_CODE	setTo (T value, 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, 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 ()
	Return the informations 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 access. 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 format 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 delete 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_32F_C1, MAT_TYPE_8U_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_32F_C1, MAT_TYPE_8U_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_32F_C1, MAT_TYPE_8U_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_32F_C1, MAT_TYPE_8U_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_32F_C1, MAT_TYPE_8U_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_32F_C1, MAT_TYPE_8U_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_32F_C1, MAT_TYPE_8U_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_32F_C1,sl::MAT_TYPE_8U_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 : specify 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 ( )

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

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 sets, you have informations in case of failure.

◆ updateGPUfromCPU()

ERROR_CODE updateGPUfromCPU ( )

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

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 sets, you have informations in case of failure.

◆ copyTo()

ERROR_CODE copyTo	(	Mat &	dst,
		COPY_TYPE	cpyType = `COPY_TYPE_CPU_CPU`
	)		const

Copies data an other Mat (deep copy).

Parameters

dst	: the Mat where the data will be copied.
cpyType	: specify the memories that will be used for the copy.

Returns: SUCCESS if everything went well, ERROR_CODE_FAILURE otherwise.

Note: If the destination is not allocated or has a not 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	: specify the memories that will be used for the update.

Returns: SUCCESS if everything went well, ERROR_CODE_FAILURE otherwise.

Note: If the current Mat is not allocated or has a not 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 (only if MEM_CPU is available on the current Mat).

Supported input files format are PNG and JPEG.

Parameters

filePath : file path including the name and extension.

Returns: SUCCESS if everything went well, ERROR_CODE_FAILURE otherwise.

Note: Supported MAT_TYPE are : MAT_TYPE_8U_C1, MAT_TYPE_8U_C3 and MAT_TYPE_8U_C4.

◆ write()

ERROR_CODE write ( const String & filePath )

Writes the Mat (only if MEM_CPU is available) into a file as an image.

Supported output files format are PNG and JPEG.

Parameters

filePath : file path including the name and extension.

Returns: SUCCESS if everything went well, ERROR_CODE_FAILURE otherwise.

Note: Supported MAT_TYPE are : MAT_TYPE_8U_C1, MAT_TYPE_8U_C3 and MAT_TYPE_8U_C4.

◆ setTo()

ERROR_CODE setTo	(	T	value,
		MEM	memory_type = `MEM_CPU`
	)

Fills the Mat with the given value.

This function overwrite 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,
		N	value,
		MEM	memory_type = `MEM_CPU`
	)

Sets a value to a specific point in the matrix.

Parameters

x	: specify the column.
y	: specify the row.
value	: the value to be set.
memory_type	: defines which memory will be updated.

Returns: 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	: specify the column
y	: specify the row
memory_type	: defines which memory should be read.

Returns: 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 : specify 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 : specify 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 : specify 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 : specify 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 ( )

Return the informations about the Mat into a String.

Returns: A string containing the Mat informations.

◆ 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 access.

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 mark 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

General Functions

Static Functions

Attributes

Detailed Description

Constructor and Destructor

◆ Mat() [1/8]

◆ Mat() [2/8]

◆ Mat() [3/8]

◆ Mat() [4/8]

◆ Mat() [5/8]

◆ Mat() [6/8]

◆ Mat() [7/8]

◆ Mat() [8/8]

◆ ~Mat()

Functions

◆ alloc() [1/2]

◆ alloc() [2/2]

◆ free()

◆ operator=()

◆ updateCPUfromGPU()

◆ updateGPUfromCPU()

◆ copyTo()

◆ setFrom()

◆ read()

◆ write()

◆ setTo()

◆ setValue()

◆ getValue()

◆ getWidth()

◆ getHeight()

◆ getResolution()

◆ getChannels()

◆ getDataType()

◆ getMemoryType()

◆ getPtr()

◆ getStepBytes()

◆ getStep() [1/2]

◆ getStep() [2/2]

◆ getPixelBytes()

◆ getWidthBytes()

◆ getInfos()

◆ isInit()

◆ isMemoryOwner()

◆ clone()

◆ move()

◆ swap()

Variables

◆ name

◆ verbose

◆ timestamp