Zed-Unity插件代码注释——ZEDMat.cs
基础环境
操作系统： Win10 专业版（不是必须的配置，只是习惯性统一写出来）
C# 版本：8.0
Unity版本：2019
Rider版本：2020
ZED型号：ZED-Mini
SDK版本：3.1
ZED-Unity插件版本：3.1
ZEDMat.cs脚本介绍
- 脚本位置
- 脚本功能：
定义了一个ZEDmat的类，这个类主要处理ZED相关的数据。这是一个矩阵类，主要用于保存ZED的RGB图像、深度图像、不同数据格式的点云、深度图像置信度数据等。 - 脚本使用：
这个脚本同样没有集成Unity中的mono类别，因此无法单独使用，挂在物品身上也没有任何反应。需要在其他脚本中实例化这个类。主要在ZEDCamera.cs和ZEDManager.cs中被调用。 同时也是我们后续开发经常需要用到的。 - 命名空间：sl
- 类名称：ZEDCamera
- 代码结构：
我在代码里面用 region语法把代码分成了几部分。
首先是在命名空间(sl)l里面定义了一些数据的结构体如图：
然后才开始定义了一个 ZEDMat的矩阵类。这个矩阵类主要分为4部分，分别为
第一部分： 定义了几个枚举类型，主要是指示矩阵的类型(浮点,无符号整型)，复制的类型(cpu和gpu的交互)，以及矩阵所在内存类型(CPU或者GPU)
第二部分： 利用[DllImport]调用外部SDK .dll文件，并声明和数据相关的函数入口，这部分可以不看，因为大部分都被定义成私有函数，外部的函数调用不到。 一般是被封装在后面的方法中。
第三部分：
1、定义了这个矩阵的指针,这个指针在后面的方法中经常用到，因为是第二部分的私有函数的传入参数。
2、定义了矩阵对象操作的一些方法，例如矩阵的创建、内存的释放、矩阵的分辨率、通道数、克隆等。这是我们在其他脚本里面可以调用的函数。
这个部分的操作层次是这个矩阵。
第四部分：
这部分的操作层面是这个矩阵内部的数据。 例如具体哪行、哪列、哪个通道、哪个位置上的元素，或者整个矩阵的数据。 主要有三种函数，分别为:
1、GetValue：获得某个像素位置上的值
2、SetValue：设置某个像素位置上的值
3、SetTo : 设置整个矩阵的值
如下图：
之所以同个函数名有八个定义，是因为矩阵数据类型主要有浮点和无符号字节两种，每一种分别又有1~4通道的类型。无符号的类型主要用于储存RGB这类型的图像，元素的值范围在0 ~ 255之间,而浮点类型的数据用于存储深度数据，点云数据，或者深度数据的置信度等。
代码（注释后的）
//======= Copyright (c) Stereolabs Corporation, All rights reserved. ===============
using System;
using System.Runtime.InteropServices;
// This file holds the ZEDMat class along with low-level structures used for passing data between
// the C# ZEDMat and its equivalent in the SDK.
// 该文件包含ZEDMat类以及用于在
// C＃ZEDMat及其在SDK中的等效项之间传递数据的低级结构。
// Lance:这个脚本里面定义了一些与ZEDSDK交互的数据类型，例如图象矩阵、深度数据矩阵等
namespace sl
{
#region 定义了一些数据的结构体
/// <summary>
/// Represents a 2D vector of uchars for use on both the CPU and GPU.
/// 表示无符号的字节的2D向量，可在CPU和GPU上使用。
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct char2
{
public byte r;
public byte g;
}
/// <summary>
/// Represents a 3D vector of uchars for use on both the CPU and GPU.
/// 表示uchar的3D向量，可在CPU和GPU上使用。
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct char3
{
public byte r;
public byte g;
public byte b;
}
/// <summary>
/// Represents a 4D vector of uchars for use on both the CPU and GPU.
/// 表示uchar的4D向量，可在CPU和GPU上使用。
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct char4
{
[MarshalAs(UnmanagedType.U1)] public byte r;
[MarshalAs(UnmanagedType.U1)] public byte g;
[MarshalAs(UnmanagedType.U1)] public byte b;
[MarshalAs(UnmanagedType.U1)] public byte a;
}
/// <summary>
/// Represents a 2D vector of floats for use on both the CPU and GPU.
/// 表示可在CPU和GPU上使用的2D浮点矢量。
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct float2
{
public float r;
public float g;
}
/// <summary>
/// Represents a 3D vector of floats for use on both the CPU and GPU.
/// 表示可在CPU和GPU上使用的3D浮点矢量。
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct float3
{
public float r;
public float g;
public float b;
}
/// <summary>
/// Represents a 4D vector of floats for use on both the CPU and GPU.
/// 表示浮点数的4D向量，可在CPU和GPU上使用。
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct float4
{
public float r;
public float g;
public float b;
public float a;
}
#endregion
/// <summary>
/// Mirrors the sl::Mat class used in the ZED C++ SDK to store images.
/// Can be used to retrieve individual images from GPU or CPU memory: see ZEDCamera.RetrieveImage()
/// and ZEDCamera.RetrieveMeasure().
/// 镜像ZED C ++ SDK中使用的sl :: Mat类来存储图像。
/// 可用于从GPU或CPU内存中检索单个图像：请参见ZEDCamera.RetrieveImage（）和ZEDCamera.RetrieveMeasure（）。
/// Lance: 主要的数据类，可以存储从SDK底层获取的数据
/// </summary><remarks>
/// For more information on the Mat class it mirrors, see:
/// https://www.stereolabs.com/developers/documentation/API/v2.5.1/classsl_1_1Mat.html
/// </remarks>
public class ZEDMat
{
#region 定义了几个枚举，主要有矩阵的类型，内存类型，复制类型
/// <summary>
/// Type of mat, indicating the data type and the number of channels it holds.
/// Proper mat type depends on the image type. See sl.VIEW and sl.MEASURE (in ZEDCommon.cs)
/// 垫子的类型，指示数据类型和它拥有的通道数。
/// 正确的垫子类型取决于图像类型。请参阅sl.VIEW和sl.MEASURE（在ZEDCommon.cs中）
/// </summary>
public enum MAT_TYPE
{
/// <summary>
/// Float, one channel. Used for depth and disparity Measure-type textures.
/// </summary>
MAT_32F_C1, //1通道浮点，用于存储某个点的深度值
/// <summary>
/// Float, two channels.
/// </summary>
MAT_32F_C2, //两通道浮点
/// <summary>
/// Float, three channels.
/// </summary>
MAT_32F_C3, /*!< float 3 channels.*/
/// <summary>
/// Float, four channels. Used for normals and XYZ (point cloud) measure-type textures
/// </summary>
MAT_32F_C4,
/// <summary>
/// Unsigned char, one channel. Used for greyscale image-type textures like depth and confidence displays.
/// </summary>
MAT_8U_C1, //无符号字节，1通道，存储图象的灰度. 0~255范围,下面依次
/// <summary>
/// Unsigned char, two channels.
/// </summary>
MAT_8U_C2,
/// <summary>
/// Unsigned char, three channels.
/// </summary>
MAT_8U_C3,
/// <summary>
/// Unsigned char, four channels. Used for color images, like the main RGB image from each sensor.
/// </summary>
MAT_8U_C4
};
/// <summary>
/// Categories for copying data within or between the CPU (processor) memory and GPU (graphics card) memory.
/// 用于在CPU（处理器）内存和GPU（图形卡）内存内或之间复制数据的类别。
/// </summary>
public enum COPY_TYPE
{
/// <summary>
/// Copies data from one place in CPU memory to another.
/// 将数据从CPU内存中的一个位置复制到另一个位置。
/// </summary>
COPY_TYPE_CPU_CPU, /*!< copy data from CPU to CPU.*/ //从CPU复制数据源到CPU另外一个地方 ,
/// <summary>
/// Copies data from CPU memory to GPU memory. //
/// </summary>
COPY_TYPE_CPU_GPU, /*!< copy data from CPU to GPU.*/ // cpu->gpu
/// <summary>
/// Copies data from one place in GPU memory to another.
/// </summary>
COPY_TYPE_GPU_GPU, /*!< copy data from GPU to GPU.*/ //gpu—>gpu
/// <summary>
/// Copies data from GPU memory to CPU memory.
/// </summary>
COPY_TYPE_GPU_CPU /*!< copy data from GPU to CPU.*/ //gpu->cpu
};
/// <summary>
/// Which memory to store an image/mat: CPU/processor memory or GPU (graphics card) memory.
/// 要存储图像/垫的内存：CPU /处理器内存或GPU（图形卡）内存。
/// </summary>
public enum MEM
{
/// <summary>
/// Store on memory accessible by the CPU.
/// 存储在CPU可以访问的内存中。
/// </summary>
MEM_CPU = 1,
/// <summary>
/// Store on memory accessible by the GPU.
/// 存储在GPU可以访问的内存中。
/// </summary>
MEM_GPU = 2
};
#endregion
#region DLL Calls 载入SDK的DLL库
const string nameDll = sl.ZEDCommon.NameDLL;
[DllImport(nameDll, EntryPoint = "dllz_mat_create_new")]
private static extern IntPtr dllz_mat_create_new(sl.Resolution resolution, int type, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_create_new_empty")]
private static extern IntPtr dllz_mat_create_new_empty();
[DllImport(nameDll, EntryPoint = "dllz_mat_is_init")]
private static extern bool dllz_mat_is_init(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_free")]
private static extern bool dllz_mat_free(System.IntPtr ptr, int type);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_infos")]
private static extern bool dllz_mat_get_infos(System.IntPtr ptr, byte[] buffer);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_value_float")]
private static extern int dllz_mat_get_value_float(System.IntPtr ptr, int x, int y, out float value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_value_float2")]
private static extern int dllz_mat_get_value_float2(System.IntPtr ptr, int x, int y, out float2 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_value_float3")]
private static extern int dllz_mat_get_value_float3(System.IntPtr ptr, int x, int y, out float3 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_value_float4")]
private static extern int dllz_mat_get_value_float4(System.IntPtr ptr, int x, int y, out float4 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_value_uchar")]
private static extern int dllz_mat_get_value_uchar(System.IntPtr ptr, int x, int y, out byte value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_value_uchar2")]
private static extern int dllz_mat_get_value_uchar2(System.IntPtr ptr, int x, int y, out char2 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_value_uchar3")]
private static extern int dllz_mat_get_value_uchar3(System.IntPtr ptr, int x, int y, out char3 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_value_uchar4")]
private static extern int dllz_mat_get_value_uchar4(System.IntPtr ptr, int x, int y, out char4 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_value_float")]
private static extern int dllz_mat_set_value_float(System.IntPtr ptr, int x, int y, ref float value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_value_float2")]
private static extern int dllz_mat_set_value_float2(System.IntPtr ptr, int x, int y, ref float2 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_value_float3")]
private static extern int dllz_mat_set_value_float3(System.IntPtr ptr, int x, int y, ref float3 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_value_float4")]
private static extern int dllz_mat_set_value_float4(System.IntPtr ptr, int x, int y, ref float4 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_value_uchar")]
private static extern int dllz_mat_set_value_uchar(System.IntPtr ptr, int x, int y, ref byte value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_value_uchar2")]
private static extern int dllz_mat_set_value_uchar2(System.IntPtr ptr, int x, int y, ref char2 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_value_uchar3")]
private static extern int dllz_mat_set_value_uchar3(System.IntPtr ptr, int x, int y, ref char3 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_value_uchar4")]
private static extern int dllz_mat_set_value_uchar4(System.IntPtr ptr, int x, int y, ref char4 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_to_float")]
private static extern int dllz_mat_set_to_float(System.IntPtr ptr, ref float value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_to_float2")]
private static extern int dllz_mat_set_to_float2(System.IntPtr ptr, ref float2 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_to_float3")]
private static extern int dllz_mat_set_to_float3(System.IntPtr ptr, ref float3 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_to_float4")]
private static extern int dllz_mat_set_to_float4(System.IntPtr ptr, ref float4 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_to_uchar")]
private static extern int dllz_mat_set_to_uchar(System.IntPtr ptr, ref byte value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_to_uchar2")]
private static extern int dllz_mat_set_to_uchar2(System.IntPtr ptr, ref char2 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_to_uchar3")]
private static extern int dllz_mat_set_to_uchar3(System.IntPtr ptr, ref char3 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_to_uchar4")]
private static extern int dllz_mat_set_to_uchar4(System.IntPtr ptr, ref char4 value, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_update_cpu_from_gpu")]
private static extern int dllz_mat_update_cpu_from_gpu(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_update_gpu_from_cpu")]
private static extern int dllz_mat_update_gpu_from_cpu(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_read")]
private static extern int dllz_mat_read(System.IntPtr ptr, string filePath);
[DllImport(nameDll, EntryPoint = "dllz_mat_write")]
private static extern int dllz_mat_write(System.IntPtr ptr, string filePath, int compression_level);
[DllImport(nameDll, EntryPoint = "dllz_mat_copy_to")]
private static extern int dllz_mat_copy_to(System.IntPtr ptr, System.IntPtr dest, int cpyType);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_width")]
private static extern int dllz_mat_get_width(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_height")]
private static extern int dllz_mat_get_height(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_channels")]
private static extern int dllz_mat_get_channels(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_memory_type")]
private static extern int dllz_mat_get_memory_type(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_pixel_bytes")]
private static extern int dllz_mat_get_pixel_bytes(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_step")]
private static extern int dllz_mat_get_step(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_step_bytes")]
private static extern int dllz_mat_get_step_bytes(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_width_bytes")]
private static extern int dllz_mat_get_width_bytes(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_is_memory_owner")]
private static extern bool dllz_mat_is_memory_owner(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_resolution")]
private static extern sl.Resolution dllz_mat_get_resolution(System.IntPtr ptr);
[DllImport(nameDll, EntryPoint = "dllz_mat_alloc")]
private static extern void dllz_mat_alloc(System.IntPtr ptr, int width, int height, int type, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_set_from")]
private static extern int dllz_mat_set_from(System.IntPtr ptr, System.IntPtr source, int copyType);
[DllImport(nameDll, EntryPoint = "dllz_mat_get_ptr")]
private static extern System.IntPtr dllz_mat_get_ptr(System.IntPtr ptr, int mem);
[DllImport(nameDll, EntryPoint = "dllz_mat_clone")]
private static extern void dllz_mat_clone(System.IntPtr ptr, System.IntPtr ptrSource);
#endregion
#region 矩阵指针，矩阵生成、初始化、内存操作、指针操作、矩阵基本信息如宽度、长度、克隆等,主要是针对矩阵这个整体对象做的操作
/// <summary>
/// Returns the internal ptr of a Mat.
/// 返回Mat的内部ptr。
/// Lance:这是一个指针，指示这个矩阵数据的地址，后面的代码中有很多操作是通过指针操作的
/// 这个指针应该是实例化的时候就自动分配的才对
/// </summary>
private System.IntPtr _matInternalPtr;
/// <summary>
/// Returns the internal ptr of a Mat.
/// 返回Mat的内部ptr。
/// </summary>
public IntPtr MatPtr
{
get {
return _matInternalPtr; }
}
/// <summary>
/// Creates an empty Mat.
/// 创建一个空的Mat。
/// </summary>
public ZEDMat()
{
_matInternalPtr = IntPtr.Zero;
}
/// <summary>
/// Creates a mat from an existing internal ptr.
/// 从现有的内部ptr创建mat。
/// Lance：从现有的内部指针创建mat变量.其实就是新建一个变量但是指向的地址是另外一个变量的地址。
/// 修改该变量得注意两边会不会冲突，不知道能不能在不同的线程之间同时访问这个地址
/// </summary>
/// <param name="ptr">IntPtr to create the material with.</param>
public ZEDMat(System.IntPtr ptr)
{
if (ptr == IntPtr.Zero)
{
throw new Exception("ZED Mat not initialized.");
}
_matInternalPtr = ptr;
}
/// <summary>
/// Creates a Mat with a given resolution.
/// 创建具有给定分辨率的mat。
/// </summary>
/// <param name="resolution">Resolution for the new Mat.新Mat的分辨率。</param>
/// <param name="type">Data type and number of channels the Mat will hold.
/// Depends on texture type: see sl.VIEW and sl.MEASURE in ZEDCommon.cs.
/// Mat将容纳的数据类型和通道数。
/// 取决于纹理类型：请参见ZEDCommon.cs中的sl.VIEW和sl.MEASURE。</param>
/// <param name="mem">Whether Mat should exist on CPU or GPU memory.
/// Choose depending on where you'll need to access it from.
/// Mat是否应存在于CPU或GPU内存上。
/// 根据您需要从何处访问它进行选择。</param>
/// Lance:这个函数应该会经常用。
public void Create(sl.Resolution resolution, MAT_TYPE type, MEM mem = MEM.MEM_CPU)
{
_matInternalPtr = dllz_mat_create_new(resolution, (int) (type), (int) (mem));
}
/// <summary>
/// Creates a Mat with a given width and height.
/// 创建具有给定宽度和高度的mat。
/// 这个和前面的函数名不是一样的吗，可能因为输入不一样所以在C#里面不会报错，因为他们的输入类型是不一样的，可能会根据输入类型自动匹配不同的函数
/// </summary>
/// <param name="width">Width of the new Mat.</param>
/// <param name="height">Height of the new Mat.</param>
/// <param name="type">Data type and number of channels the Mat will hold.
/// Depends on texture type: see sl.VIEW and sl.MEASURE in ZEDCommon.cs.</param>
/// <param name="mem">Whether Mat should exist on CPU or GPU memory.
/// Choose depending on where you'll need to access it from.</param>
public void Create(uint width, uint height, MAT_TYPE type, MEM mem = MEM.MEM_CPU)
{
_matInternalPtr = dllz_mat_create_new(new sl.Resolution(width, height), (int) (type), (int) (mem));
}
/// <summary>
/// True if the Mat has been initialized.
/// 真：已经初始化
/// Lance：指定这个矩阵实例是否已经有了数据
/// </summary>
/// <returns></returns>
public bool IsInit()
{
return dllz_mat_is_init(_matInternalPtr);
}
/// <summary>
/// Frees the memory of the Mat.
/// 释放这个矩阵的内存
/// </summary>
/// <param name="mem">Whether the Mat is on CPU or GPU memory.</param>
public void Free(MEM mem = (MEM.MEM_GPU | MEM.MEM_CPU))
{
dllz_mat_free(_matInternalPtr, (int) mem);
_matInternalPtr = IntPtr.Zero;
}
/// <summary>
/// Copies data from the GPU to the CPU, if possible.
/// 可以的话，把数据从gpu复制到cpu然后获得相应的指针,
/// Lance：应该是复制过去后指针也会自动更改，这里有个问题，应该会自动释放掉原来那部分的内存
/// 所以这边用剪切是不是更合适一点？把数据剪切到另外一个地方，释放掉原来的内存
/// </summary>
/// <returns></returns>
public sl.ERROR_CODE UpdateCPUFromGPU()
{
return (sl.ERROR_CODE) dllz_mat_update_cpu_from_gpu(_matInternalPtr);
}
/// <summary>
/// Copies data from the CPU to the GPU, if possible.
/// 把数据从cpu移植到gpu
/// </summary>
/// <returns></returns>
public sl.ERROR_CODE UpdateGPUFromCPU()
{
return (sl.ERROR_CODE) dllz_mat_update_gpu_from_cpu(_matInternalPtr);
}
/// <summary>
/// Returns information about the Mat.
/// 返回这个矩阵的信息
/// </summary>
/// <returns>String providing Mat information.</returns>
public string GetInfos()
{
byte[] buf = new byte[300];
dllz_mat_get_infos(_matInternalPtr, buf);
return System.Text.Encoding.ASCII.GetString(buf);
}
/// <summary>
/// Copies data from this Mat to another Mat (deep copy).
/// 复制这个矩阵到另外一个矩阵，（深拷贝）
/// Lance：深拷贝，指的是完全是新开辟一块内存，和指针变量， 拷贝完与原来的变量无关
/// </summary>
/// <param name="dest">Mat that the data will be copied to.需要复制数据的对象(不是被复制的)</param>
/// <param name="copyType">The To and From memory types.</param>
/// <returns>Error code indicating if the copy was successful, or why it wasn't.</returns>
public sl.ERROR_CODE CopyTo(sl.ZEDMat dest, sl.ZEDMat.COPY_TYPE copyType = COPY_TYPE.COPY_TYPE_CPU_CPU)
{
return (sl.ERROR_CODE) dllz_mat_copy_to(_matInternalPtr, dest._matInternalPtr, (int) (copyType));
}
/// <summary>
/// Reads an image from a file. Supports .png and .jpeg. Only works if Mat has access to MEM_CPU.
/// 从文件中读取图像。支持.png和.jpeg。仅在Mat可以访问MEM_CPU时才起作用。
/// </summary>
/// <param name="filePath">File path, including file name and extension.</param>
/// <returns>Error code indicating if the read was successful, or why it wasn't.</returns>
public sl.ERROR_CODE Read(string filePath)
{
return (sl.ERROR_CODE) dllz_mat_read(_matInternalPtr, filePath);
}
/// <summary>
/// Writes the Mat into a file as an image. Only works if Mat has access to MEM_CPU.
/// 将Mat作为图像写入文件。仅在Mat可以访问MEM_CPU时才起作用。
/// </summary>
/// <param name="filePath">File path, including file name and extension.</param>
/// <param name="compression_level"> Compression level used. Highest value means highest compression (smaller size). Range : [0 - 100].</param>
/// <returns>Error code indicating if the write was successful, or why it wasn't.</returns>
public sl.ERROR_CODE Write(string filePath, int compressionLevel = -1)
{
return (sl.ERROR_CODE) dllz_mat_write(_matInternalPtr, filePath, compressionLevel);
}
/// <summary>
/// Returns the width of the matrix.
/// 返回矩阵的宽度。
/// </summary>
/// <returns></returns>
public int GetWidth()
{
return dllz_mat_get_width(_matInternalPtr);
}
/// <summary>
/// Returns the height of the matrix.
/// 返回矩阵的高度
/// </summary>
/// <returns></returns>
public int GetHeight()
{
return dllz_mat_get_height(_matInternalPtr);
}
/// <summary>
/// Returns the number of values/channels stored in each pixel.
/// 返回每一个像素点的通道数
/// Lance： rgb 为3 depth 为1 点云（XYZ）为3
/// </summary>
/// <returns>Number of values/channels.</returns>
public int GetChannels()
{
return dllz_mat_get_channels(_matInternalPtr);
}
/// <summary>
/// Returns the size in bytes of one pixel.
/// 返回一个像素的字节尺寸
/// </summary>
/// <returns>Size in bytes.</returns>
public int GetPixelBytes()
{
return dllz_mat_get_pixel_bytes(_matInternalPtr);
}
/// <summary>
/// Returns the memory 'step' in number/length of elements - how many values make up each row of pixels.
/// 返回内存“步长”，以元素的数量/长度为单位-每行像素有多少个值。
/// </summary>
/// <returns>Step length.</returns>
public int GetStep()
{
return dllz_mat_get_step(_matInternalPtr);
}
/// <summary>
/// Returns the memory 'step' in bytes - how many bytes make up each row of pixels.
/// 一个元素占用多少字节
/// </summary>
/// <returns></returns>
public int GetStepBytes()
{
return dllz_mat_get_step_bytes(_matInternalPtr);
}
/// <summary>
/// Returns the size of each row in bytes.
/// 返回每行的大小（以字节为单位）。
/// </summary>
/// <returns></returns>
public int GetWidthBytes()
{
return dllz_mat_get_width_bytes(_matInternalPtr);
}
/// <summary>
/// Returns the type of memory (CPU and/or GPU).
/// 返回内存的类型（CPU和/或GPU）。
/// Lance：当前矩阵实例的内存类型
/// </summary>
/// <returns></returns>
public MEM GetMemoryType()
{
return (MEM) dllz_mat_get_memory_type(_matInternalPtr);
}
/// <summary>
/// Returns whether the Mat is the owner of the memory it's accessing.
/// 返回Mat是否是其正在访问的内存的所有者。
/// Lance:这边的意思应该指的是，确定一下是不是这个矩阵指向的内存是这个矩阵创建的。
/// 如果是浅拷贝的矩阵，它指向的内存地址就不是由它最初创建的，不一定有修改的权限，可能只有读取的权限
/// </summary>
/// <returns></returns>
public bool IsMemoryOwner()
{
return dllz_mat_is_memory_owner(_matInternalPtr);
}
/// <summary>
/// Returns the resolution of the image that this Mat holds.
/// 返回分辨率
/// </summary>
/// <returns></returns>
public sl.Resolution GetResolution()
{
return dllz_mat_get_resolution(_matInternalPtr);
}
/// <summary>
/// Allocates memory for the Mat.
/// 为这个矩阵分配内存
/// </summary>
/// <param name="width">Width of the image/matrix in pixels.</param>
/// <param name="height">Height of the image/matrix in pixels.</param>
/// <param name="matType">Type of matrix (data type and channels; see sl.MAT_TYPE)</param>
/// <param name="mem">Where the buffer will be stored - CPU memory or GPU memory.</param>
public void Alloc(uint width, uint height, MAT_TYPE matType, MEM mem = MEM.MEM_CPU)
{
dllz_mat_alloc(_matInternalPtr, (int) width, (int) height, (int) matType, (int) mem);
}
/// <summary>
/// Allocates memory for the Mat.
/// 分配内存
/// </summary>
/// <param name="resolution">Size of the image/matrix in pixels.</param>
/// <param name="matType">Type of matrix (data type and channels; see sl.MAT_TYPE)</param>
/// <param name="mem">Where the buffer will be stored - CPU memory or GPU memory.</param>
public void Alloc(sl.Resolution resolution, MAT_TYPE matType, MEM mem = MEM.MEM_CPU)
{
dllz_mat_alloc(_matInternalPtr, (int) resolution.width, (int) resolution.height, (int) matType, (int) mem);
}
/// <summary>
/// Copies data from another Mat into this one(deep copy).
/// 从其他的矩阵中拷贝数据到这个矩阵中，是深拷贝
/// </summary>
/// <param name="src">Source Mat from which to copy.</param>
/// <param name="copyType">The To and From memory types.</param>
/// <returns>ERROR_CODE (as an int) indicating if the copy was successful, or why it wasn't.</returns>
public int SetFrom(ZEDMat src, COPY_TYPE copyType = COPY_TYPE.COPY_TYPE_CPU_CPU)
{
return dllz_mat_set_from(_matInternalPtr, src._matInternalPtr, (int) copyType);
}
public System.IntPtr GetPtr(MEM mem = MEM.MEM_CPU)
{
return dllz_mat_get_ptr(_matInternalPtr, (int) mem);
}
/// <summary>
/// Duplicates a Mat by copying all its data into a new one (deep copy).
/// 克隆一个矩阵，但是是深拷贝。
/// </summary>
/// <param name="source"></param>
public void Clone(ZEDMat source)
{
dllz_mat_clone(_matInternalPtr, source._matInternalPtr);
}
#endregion
#region 初始完成后，进一步对矩阵数据进行操作，数据类型有浮点和无符号字节两种， 每一种分别由1~4通道的类型，所以每一种数据操作函数都有8个同样名称但是不同输入的情况
/************ GET VALUES *********************/
//Cannot send values by template due to a covariant issue with an out needed.
/// <summary>
/// Returns the value of a specific point in the matrix. (MAT_32F_C1)
/// 返回矩阵中特定点的值。这个值的类型是单通道的 （MAT_32F_C1）
/// </summary>
/// <param name="x">Row the point is in.该点所在的行</param>
/// <param name="y">Column the point is in.该点所在的列</param>
/// <param name="value">Gets filled with the current value.该店所在的值</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.该点所在的内存类型</param>
/// <returns>Error code indicating if the get was successful, or why it wasn't.</returns>
public sl.ERROR_CODE GetValue(int x, int y, out float value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_get_value_float(_matInternalPtr, x, y, out value, (int) (mem)));
}
/// <summary>
/// Returns the value of a specific point in the matrix. (MAT_32F_C2)
/// 返回矩阵中特定点的值。这个点的值是双通道浮点（MAT_32F_C2）
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Gets filled with the current value.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the get was successful, or why it wasn't.</returns>
public sl.ERROR_CODE GetValue(int x, int y, out float2 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_get_value_float2(_matInternalPtr, x, y, out value, (int) (mem)));
}
/// <summary>
/// Returns the value of a specific point in the matrix. (MAT_32F_C3)
/// 3通道浮点
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Gets filled with the current value.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the get was successful, or why it wasn't.</returns>
/// Lance：这个函数可以用来获取点云矩阵中具体某个像素点的值
public sl.ERROR_CODE GetValue(int x, int y, out float3 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_get_value_float3(_matInternalPtr, x, y, out value, (int) (mem)));
}
/// <summary>
/// Returns the value of a specific point in the matrix. (MAT_32F_C4)
/// 4通道浮点
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Gets filled with the current value.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the get was successful, or why it wasn't.</returns>
public sl.ERROR_CODE GetValue(int x, int y, out float4 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_get_value_float4(_matInternalPtr, x, y, out value, (int) (mem)));
}
/// <summary>
/// Returns the value of a specific point in the matrix. (MAT_TYPE_8U_C1)
/// 1通道1字节 下面依次类推
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Gets filled with the current value.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the get was successful, or why it wasn't.</returns>
public sl.ERROR_CODE GetValue(int x, int y, out byte value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_get_value_uchar(_matInternalPtr, x, y, out value, (int) (mem)));
}
/// <summary>
/// Returns the value of a specific point in the matrix. (MAT_TYPE_8U_C2)
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Gets filled with the current value.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the get was successful, or why it wasn't.</returns>
public sl.ERROR_CODE GetValue(int x, int y, out char2 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_get_value_uchar2(_matInternalPtr, x, y, out value, (int) (mem)));
}
/// <summary>
/// Returns the value of a specific point in the matrix. (MAT_TYPE_8U_C3)
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Gets filled with the current value.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the get was successful, or why it wasn't.</returns>
public sl.ERROR_CODE GetValue(int x, int y, out char3 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_get_value_uchar3(_matInternalPtr, x, y, out value, (int) (mem)));
}
/// <summary>
/// Returns the value of a specific point in the matrix. (MAT_TYPE_8U_C4)
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Gets filled with the current value.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the get was successful, or why it wasn't.</returns>
public sl.ERROR_CODE GetValue(int x, int y, out char4 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_get_value_uchar4(_matInternalPtr, x, y, out value, (int) (mem)));
}
/***************************************************************************************/
/************ SET VALUES *********************/
//Cannot send values by template due to a covariant issue with an out needed.
//对某个位置进行赋值
/// <summary>
/// Sets a value to a specific point in the matrix. (MAT_32F_C1)
/// 将值设置为矩阵中的特定点。单通道浮点，下面依次类推 （MAT_32F_C1）
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Value to which the point will be set.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetValue(int x, int y, ref float value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_value_float(_matInternalPtr, x, y, ref value, (int) (mem)));
}
/// <summary>
/// Sets a value to a specific point in the matrix. (MAT_32F_C2)
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Value to which the point will be set.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetValue(int x, int y, ref float2 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_value_float2(_matInternalPtr, x, y, ref value, (int) (mem)));
}
/// <summary>
/// Sets a value to a specific point in the matrix. (MAT_32F_C3)
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Value to which the point will be set.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetValue(int x, int y, ref float3 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_value_float3(_matInternalPtr, x, y, ref value, (int) (mem)));
}
/// <summary>
/// Sets a value to a specific point in the matrix. (MAT_32F_C4)
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Value to which the point will be set.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetValue(int x, int y, float4 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_value_float4(_matInternalPtr, x, y, ref value, (int) (mem)));
}
/// <summary>
/// Sets a value to a specific point in the matrix. (MAT_TYPE_8U_C1)
/// 将值设置为矩阵中的特定点。单通道1字节，下面依次类推 （MAT_TYPE_8U_C1）
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Value to which the point will be set.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetValue(int x, int y, ref byte value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_value_uchar(_matInternalPtr, x, y, ref value, (int) (mem)));
}
/// <summary>
/// Sets a value to a specific point in the matrix. (MAT_TYPE_8U_C2)
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Value to which the point will be set.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetValue(int x, int y, ref char2 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_value_uchar2(_matInternalPtr, x, y, ref value, (int) (mem)));
}
/// <summary>
/// Sets a value to a specific point in the matrix. (MAT_TYPE_8U_C3)
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Value to which the point will be set.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetValue(int x, int y, ref char3 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_value_uchar3(_matInternalPtr, x, y, ref value, (int) (mem)));
}
/// <summary>
/// Sets a value to a specific point in the matrix. (MAT_TYPE_8U_C4)
/// </summary>
/// <param name="x">Row the point is in.</param>
/// <param name="y">Column the point is in.</param>
/// <param name="value">Value to which the point will be set.</param>
/// <param name="mem">Whether point is on CPU memory or GPU memory.</param>
/// <returns>Error code indicating if the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetValue(int x, int y, ref char4 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_value_uchar4(_matInternalPtr, x, y, ref value, (int) (mem)));
}
/***************************************************************************************/
/************ SET TO *********************/
//Cannot send values by template due to a covariant issue with an out needed.
//由于协变问题而需要out，因此无法按模板发送值。
// 下面是对矩阵的所有值进行覆盖
/// <summary>
/// Fills the entire Mat with the given value. (MAT_32F_C1)
/// 用给定值填充整个Mat。 （MAT_32F_C1）
/// </summary>
/// <param name="value">Value with which to fill the Mat.</param>
/// <param name="mem">Which buffer to fill - CPU or GPU memory.</param>
/// <returns>Whether the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetTo(ref float value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_to_float(_matInternalPtr, ref value, (int) (mem)));
}
/// <summary>
/// Fills the entire Mat with the given value. (MAT_32F_C2)
/// </summary>
/// <param name="value">Value with which to fill the Mat.</param>
/// <param name="mem">Which buffer to fill - CPU or GPU memory.</param>
/// <returns>Whether the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetTo(ref float2 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_to_float2(_matInternalPtr, ref value, (int) (mem)));
}
/// <summary>
/// Fills the entire Mat with the given value. (MAT_32F_C3)
/// </summary>
/// <param name="value">Value with which to fill the Mat.</param>
/// <param name="mem">Which buffer to fill - CPU or GPU memory.</param>
/// <returns>Whether the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetTo(ref float3 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_to_float3(_matInternalPtr, ref value, (int) (mem)));
}
/// <summary>
/// Fills the entire Mat with the given value. (MAT_32F_C4)
/// </summary>
/// <param name="value">Value with which to fill the Mat.</param>
/// <param name="mem">Which buffer to fill - CPU or GPU memory.</param>
/// <returns>Whether the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetTo(ref float4 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_to_float4(_matInternalPtr, ref value, (int) (mem)));
}
/// <summary>
/// Fills the entire Mat with the given value. (MAT_TYPE_8U_C1)
/// </summary>
/// <param name="value">Value with which to fill the Mat.</param>
/// <param name="mem">Which buffer to fill - CPU or GPU memory.</param>
/// <returns>Whether the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetTo(ref byte value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_to_uchar(_matInternalPtr, ref value, (int) (mem)));
}
/// <summary>
/// Fills the entire Mat with the given value. (MAT_TYPE_8U_C2)
/// </summary>
/// <param name="value">Value with which to fill the Mat.</param>
/// <param name="mem">Which buffer to fill - CPU or GPU memory.</param>
/// <returns>Whether the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetTo(ref char2 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_to_uchar2(_matInternalPtr, ref value, (int) (mem)));
}
/// <summary>
/// Fills the entire Mat with the given value. (MAT_TYPE_8U_C3)
/// </summary>
/// <param name="value">Value with which to fill the Mat.</param>
/// <param name="mem">Which buffer to fill - CPU or GPU memory.</param>
/// <returns>Whether the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetTo(ref char3 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_to_uchar3(_matInternalPtr, ref value, (int) (mem)));
}
/// <summary>
/// Fills the entire Mat with the given value. (MAT_TYPE_8U_C4)
/// </summary>
/// <param name="value">Value with which to fill the Mat.</param>
/// <param name="mem">Which buffer to fill - CPU or GPU memory.</param>
/// <returns>Whether the set was successful, or why it wasn't.</returns>
public sl.ERROR_CODE SetTo(ref char4 value, sl.ZEDMat.MEM mem)
{
return (sl.ERROR_CODE) (dllz_mat_set_to_uchar4(_matInternalPtr, ref value, (int) (mem)));
}
/***************************************************************************************/
#endregion
}
}