AR SDK 编程指南

AR SDK 编程指南

AR SDK 编程指南提供了关于如何在您的应用程序中使用 AR SDK 的信息，并提供了 API 参考列表。

本节提供关于 NVIDIA® AR SDK API 架构的信息。

1.1. 在应用程序中使用 NVIDIA AR SDK

使用 AR SDK 可以使应用程序使用 SDK 的面部跟踪、面部地标跟踪、3D 面部网格跟踪和 3D 身体姿势跟踪功能。

1.2. 创建功能类型的实例

功能类型是一个预定义的结构，用于访问 SDK 功能。每个功能都需要功能类型的实例化。

创建功能类型的实例可以访问配置参数，这些参数在加载功能类型实例时使用，以及在运行时提供功能类型实例时使用的输入和输出参数。

1. 为 NvAR_FeatureHandle 结构分配内存。
   复制

   已复制！

               
   
               
   NvAR_FeatureHandle faceDetectHandle{};
           

2. 调用 NvAR_Create() 函数。在函数调用中，传递以下信息：
   • NvAR_FeatureID 枚举的值，用于标识功能类型。
   • 指向您声明的变量的指针，该变量用于为 NvAR_FeatureHandle 结构分配内存。
3. 要创建面部检测功能类型的实例，请运行以下示例
   复制

   已复制！

               
   
               
   NvAR_Create(NvAR_Feature_FaceDetection, &faceDetectHandle)
           

   
   

   此函数创建一个功能实例的句柄，该句柄在函数调用中是必需的，用于获取和设置实例的属性以及加载、运行或销毁实例。

1.3. 获取和设置功能类型的属性

为了准备加载和运行功能类型的实例，您需要设置实例所需的属性。

以下是一些属性：

• 加载功能类型所需的配置属性。
• 输入和输出属性在运行时提供，当功能类型的实例运行时。

有关属性的完整列表，请参阅功能类型属性中的键值。

为了设置属性，NVIDIA AR SDK 提供了类型安全的设置访问器函数。如果您需要已由设置访问器函数设置的属性的值，请使用相应的获取访问器函数。有关获取和设置函数的完整列表，请参阅NVIDIA AR SDK 访问器函数摘要。

1.3.1. 设置 CUDA 流

某些 SDK 功能需要 CUDA 流才能运行。有关更多信息，请参阅 NVIDIA CUDA 工具包文档。

1. 通过调用以下函数之一来初始化 CUDA 流：
   • CUDA 运行时 API 函数 cudaStreamCreate()
   • NvAR_CudaStreamCreate()

   您可以使用第二个函数来避免与 NVIDIA CUDA 工具包库链接。

2. 调用 NvAR_SetCudaStream() 函数并提供以下信息作为参数：
   • 创建的过滤器句柄。

     有关更多信息，请参阅创建功能类型的实例。

   • 键值 NVAR_Parameter_Config(CUDAStream)。

     有关更多信息，请参阅功能类型属性中的键值。

   • 您在上一步中创建的 CUDA 流。

   此示例设置通过调用 NvAR_CudaStreamCreate() 函数创建的 CUDA 流

   复制

   已复制！

               
   
               
   CUstream stream;
   nvErr = NvAR_CudaStreamCreate (&stream);
   nvErr = NvAR_SetCudaStream(featureHandle, NVAR_Parameter_Config(CUDAStream), stream);
           

   
   

1.3.2. NVIDIA AR SDK 访问器函数摘要

下表提供了有关 SDK 访问器函数的详细信息。

1.3.3. 功能类型属性中的键值

功能类型属性中的键值标识可以与每种功能类型一起使用的属性。每个键都有一个字符串等效项，并且由一个宏定义，该宏指示属性的类别并接受名称作为宏的输入。

以下是指示属性类别的宏：

• NvAR_Parameter_Config 指示配置属性。

  有关更多信息，请参阅配置属性。

• NvAR_Parameter_Input 指示输入属性。

  有关更多信息，请参阅输入属性。

• NvAR_Parameter_Output 指示输出属性。

  有关更多信息，请参阅输出属性。

这些名称是固定的关键字，并在 nvAR_defs.h 中列出。关键字可能会与不同的宏重用，具体取决于属性是输入属性、输出属性还是配置属性。

属性类型表示用于设置和获取属性的访问器函数，如 NVIDIA AR SDK 访问器函数摘要 表中列出。

1.3.3.1. 配置属性

以下是 AR SDK 中的配置属性

NvAR_Parameter_Config(FeatureDescription)

功能类型的描述。

字符串等效项：NvAR_Parameter_Config_FeatureDescription

属性类型：字符串 (const char*)

NvAR_Parameter_Config(CUDAStream)

运行功能的 CUDA 流。

字符串等效项：NvAR_Parameter_Config_CUDAStream

属性类型：CUDA 流 (CUstream)

NvAR_Parameter_Config(ModelDir)

包含 TensorRT 模型文件的目录路径，这些模型文件将用于运行面部检测或地标检测的推理，以及包含 3D 面部模型的 .nvf 文件，不包括模型文件名。有关 .nvf 文件格式的详细信息，请参阅NVIDIA 3DMM 文件格式。

字符串等效项：NvAR_Parameter_Config_ModelDir

属性类型：字符串 (const char*)

NvAR_Parameter_Config(BatchSize)

在 GPU 上一次运行的推理次数。

字符串等效项：NvAR_Parameter_Config_BatchSize

属性类型：unsigned integer

NvAR_Parameter_Config(Landmarks_Size)

输出缓冲区的长度，其中包含检测到的地标的像素 X 和 Y 坐标。此属性仅适用于地标检测功能。

字符串等效项：NvAR_Parameter_Config_Landmarks_Size

属性类型：unsigned integer

NvAR_Parameter_Config(LandmarksConfidence_Size)

输出缓冲区的长度，其中包含检测到的地标的置信度值。此属性仅适用于地标检测功能。

字符串等效项：NvAR_Parameter_Config_LandmarksConfidence_Size

属性类型：unsigned integer

NvAR_Parameter_Config(Temporal)

启用时间输入帧优化的标志。当输入是视频时，启用此标志。

字符串等效项：NvAR_Parameter_Config_Temporal

属性类型：unsigned integer

NvAR_Parameter_Config(ShapeEigenValueCount)

用于描述形状的特征值的数量。在提供的 face_model2.nvf 中，有 100 个形状（也称为身份）特征值，但在分配数组以接收特征值时，应查询 ShapeEigenValueCount。

字符串等效项：NvAR_Parameter_Config_ShapeEigenValueCount

属性类型：unsigned integer

NvAR_Parameter_Config(ExpressionCount)

用于表示表情的系数数量。在提供的 face_model2.nvf 中，有 53 个表情 blendshape 系数，但在分配数组以接收系数时，应查询ExpressionCount。

字符串等效项：NvAR_Parameter_Config_ExpressionCount

属性类型：unsigned integer

NvAR_Parameter_Config(UseCudaGraph)

启用 CUDA Graph 优化的标志。CUDA 图减少了 3D 身体跟踪的 GPU 操作提交开销。

字符串等效项：NvAR_Parameter_Config_UseCudaGraph

属性类型：bool

NvAR_Parameter_Config(Mode)

为 3D 身体姿势或面部地标检测选择高性能或高质量的模式。

字符串等效项：NvAR_Parameter_Config_Mode

属性类型：unsigned int

NvAR_Parameter_Config(ReferencePose)

NvAR_Point3f 类型的 CPU 缓冲区，用于保存 3D 身体姿势的关节旋转的参考姿势。

字符串等效项：NvAR_Parameter_Config_ReferencePose

属性类型：对象 (void*)

NvAR_Parameter_Config(TrackPeople) (仅限 Windows)

为 3D 身体姿势跟踪选择多人跟踪的标志。

字符串等效项：NvAR_Parameter_Config_TrackPeople

属性类型：对象 (unsigned integer)

NvAR_Parameter_Config(ShadowTrackingAge)(仅限 Windows)

多人跟踪器不再以阴影模式跟踪对象的年龄。此属性以帧数为单位衡量。

为 3D 身体姿势跟踪选择多人跟踪的标志。

字符串等效项：NvAR_Parameter_Config_ShadowTrackingAge

属性类型：对象 (unsigned integer)

NvAR_Parameter_Config(ProbationAge)(仅限 Windows)

多人跟踪器将对象标记为有效并分配 ID 以进行跟踪的年龄。此属性以帧数为单位衡量。

字符串等效项：NvAR_Parameter_Config_ProbationAge

属性类型：对象 (unsigned integer)

NvAR_Parameter_Config(MaxTargetsTracked)(仅限 Windows)

多人跟踪器要跟踪的最大目标数。达到新的最大目标跟踪限制后，任何新目标都将被丢弃。

字符串等效项：NvAR_Parameter_Config_MaxTargetsTracked

属性类型：对象 (unsigned integer)

1.3.3.2. 输入属性

以下是 AR SDK 中的输入属性

NvAR_Parameter_Input(Image)

NvCVImage 类型的 GPU 输入图像缓冲区。

字符串等效项：NvAR_Parameter_Input_Image

属性类型：对象 (void*)

NvAR_Parameter_Input(Width)

输入图像缓冲区的宽度，以像素为单位。

字符串等效项：NvAR_Parameter_Input_Width

属性类型：integer

NvAR_Parameter_Input(Height)

输入图像缓冲区的高度，以像素为单位。

字符串等效项：NvAR_Parameter_Input_Height

属性类型：integer

NvAR_Parameter_Input(Landmarks)

NvAR_Point2f 类型的 CPU 输入数组，其中包含面部地标点。

字符串等效项：NvAR_Parameter_Input_Landmarks

属性类型：对象 (void*)

NvAR_Parameter_Input(BoundingBoxes)

边界框，用于确定输入图像的感兴趣区域 (ROI)，其中包含 NvAR_BBoxes 类型的面部。

字符串等效项：NvAR_Parameter_InputBoundingBoxes

属性类型：对象 (void*)

NvAR_Parameter_Input(FocalLength)

用于 3D 身体姿势的相机的焦距。

字符串等效项：NvAR_Parameter_Input_FocalLength

属性类型：对象 (float)

1.3.3.3. 输出属性

以下是 AR SDK 中的输出属性

NvAR_Parameter_Output(BoundingBoxes)

NvAR_BBoxes 类型的 CPU 输出边界框。

字符串等效项：NvAR_Parameter_Output_BoundingBoxes

属性类型：对象 (void*)

NvAR_Parameter_Output(TrackingBoundingBoxes)(仅限 Windows)

NvAR_TrackingBBoxes 类型的 CPU 输出跟踪边界框。

字符串等效项：NvAR_Parameter_Output_TrackingBBoxes

属性类型：对象 (object (void*))

NvAR_Parameter_Output(BoundingBoxesConfidence)

每个返回的边界框的置信度值的浮点数组。

字符串等效项：NvAR_Parameter_Output_BoundingBoxesConfidence

属性类型：浮点数组

NvAR_Parameter_Output(Landmarks)

NvAR_Point2f 类型的 CPU 输出缓冲区，用于保存输出检测到的地标关键点。有关更多信息，请参阅面部点注释。CPU 缓冲区中点的顺序遵循 MultiPIE 68 点标记中的顺序，126 个点覆盖脸颊、眼睛和笑纹沿线的更多点。

字符串等效项：NvAR_Parameter_Output_Landmarks

属性类型：对象 (void*)

NvAR_Parameter_Output(LandmarksConfidence)

每个检测到的地标点的置信度值的浮点数组。

字符串等效项：NvAR_Parameter_Output_LandmarksConfidence

属性类型：浮点数组

NvAR_Parameter_Output(Pose)

NvAR_Quaternion 类型的 CPU 数组，用于保存输出检测到的姿势，以 XYZW 四元数表示。

字符串等效项：NvAR_Parameter_Output_Pose

属性类型：对象 (void*)

NvAR_Parameter_Output(FaceMesh)

NvAR_FaceMesh 类型的 CPU 3D 面部网格。

字符串等效项：NvAR_Parameter_Output_FaceMesh

属性类型：对象 (void*)

NvAR_Parameter_Output(RenderingParams)

NvAR_RenderingParams 类型的 CPU 输出结构，其中包含可能用于渲染 3D 面部网格的渲染参数。

字符串等效项：NvAR_Parameter_Output_RenderingParams

属性类型：对象 (void*)

NvAR_Parameter_Output(ShapeEigenValues)

形状特征值的浮点数组。获取 NvAR_Parameter_Config(ShapeEigenValueCount) 以确定有多少特征值。

字符串等效项：NvAR_Parameter_Output_ShapeEigenValues

属性类型：const 浮点数组

NvAR_Parameter_Output(ExpressionCoefficients)

表情系数的浮点数组。获取 NvAR_Parameter_Config(ExpressionCount) 以确定有多少系数。

字符串等效项：NvAR_Parameter_Output_ExpressionCoefficients

属性类型：const 浮点数组

NvAR_Parameter_Output(KeyPoints)

NvAR_Point2f 类型的 CPU 输出缓冲区，用于保存输出检测到的身体姿势的 2D 关键点。有关关键点名称和关键点输出顺序的信息，请参阅3D 身体姿势关键点格式。

字符串等效项：NvAR_Parameter_Output_KeyPoints

属性类型：对象 (void*)

NvAR_Parameter_Output(KeyPoints3D)

NvAR_Point3f 类型的 CPU 输出缓冲区，用于保存输出检测到的身体姿势的 3D 关键点。有关关键点名称和关键点输出顺序的信息，请参阅3D 身体姿势关键点格式。

字符串等效项：NvAR_Parameter_Output_KeyPoints3D

属性类型：对象 (void*)

NvAR_Parameter_Output(JointAngles)

NvAR_Point3f 类型的 CPU 输出缓冲区，用于保存身体姿势关键点的轴角格式的关节角度。

字符串等效项：NvAR_Parameter_Output_JointAngles

属性类型：对象 (void*)

NvAR_Parameter_Output(KeyPointsConfidence)

每个检测到的关键点的置信度值的浮点数组。

字符串等效项：NvAR_Parameter_Output_KeyPointsConfidence

属性类型：浮点数组

NvAR_Parameter_Output(OutputHeadTranslation)

包含三个值的浮点数组，表示眼睛接触时头部相对于相机的平移的 x、y 和 z 值。

字符串等效项：NvAR_Parameter_Output_OutputHeadTranslation

属性类型：浮点数组

NvAR_Parameter_Output(OutputGazeVector)

包含两个值的浮点数组，表示眼睛接触时估计凝视的偏航角和俯仰角。

字符串等效项：NvAR_Parameter_Output_OutputGazeVector

属性类型：浮点数组

NvAR_Parameter_Output(HeadPose)

NvAR_Quaternion 类型的 CPU 数组，用于保存在眼睛接触时输出检测到的头部姿势，以 XYZW 四元数表示。这是从面部地标特征获得的头部姿势的替代方案。此头部姿势是使用地标上的 PnP 算法获得的。

字符串等效项：NvAR_Parameter_Output_HeadPose

属性类型：object (void*)

NvAR_Parameter_Output(GazeDirection)

包含两个值的浮点数组，表示眼睛接触时估计凝视的偏航角和俯仰角。

字符串等效项：NvAR_Parameter_Output_GazeDirection

属性类型：浮点数组

1.3.4. 获取功能属性的值

要获取功能属性的值，请调用适合属性数据类型的 get 访问器函数。

在函数调用中，传递以下信息：

• 功能实例的功能句柄。
• 标识您要获取的属性的键值。
• 您希望将属性值写入的内存位置。

此示例确定地标检测功能返回的 NvAR_Point2f 输出缓冲区的长度

            

            
unsigned int OUTPUT_SIZE_KPTS;
NvAR_GetU32(landmarkDetectHandle, NvAR_Parameter_Config(Landmarks_Size), &OUTPUT_SIZE_KPTS);
        

1.3.5. 为功能设置属性

以下步骤说明如何为功能设置属性。

1. 为功能所需的所有输入和输出以及可能需要的任何其他属性分配内存。
2. 调用适合属性数据类型的 set 访问器函数。在函数调用中，传递以下信息：
   • 功能实例的功能句柄。
   • 标识您要设置的属性的键值。
   • 指向您要将属性设置为的值的指针。

   此示例设置包含输出 3D 面部模型的文件的文件路径

   复制

   已复制！

               
   
               
   const char *modelPath = "file/path/to/model";
   NvAR_SetString(landmarkDetectHandle, NvAR_Parameter_Config(ModelDir), modelPath);
           

   
   此示例在 GPU 内存中设置输入图像缓冲区，这是面部检测功能所必需的

   注意

   它设置了一个 8 位 chunky/交错 BGR 数组。

   复制

   已复制！

               
   
               
   NvCVImage InputImageBuffer;
   NvCVImage_Alloc(&inputImageBuffer, input_image_width, input_image_height, NVCV_BGR, NVCV_U8, NVCV_CHUNKY, NVCV_GPU, 1) ;
   NvAR_SetObject(landmarkDetectHandle, NvAR_Parameter_Input(Image), &InputImageBuffer, sizeof(NvCVImage));
           

   
   

   有关每个功能的属性以及输入和输出要求的更多信息，请参阅 AR 功能的属性列表。

   注意

   列出的属性名称是宏的输入，该宏定义属性的键值。

   
   

1.3.6. 加载功能实例

在设置加载功能类型实例所需的配置属性后，您可以加载该功能。

要加载功能实例，请调用 NvAR_Load() 函数，并指定在创建实例时为功能实例创建的句柄。有关更多信息，请参阅创建功能类型的实例。

此示例加载面部检测功能类型的实例

            

            
NvAR_Load(faceDetectHandle);
        

1.3.7. 运行功能实例

在您可以运行功能实例之前，加载功能类型的实例并设置在运行功能实例时所需的用户分配的输入和输出内存缓冲区。

要运行功能实例，请调用 NvAR_Run() 函数，并指定在创建实例时为功能实例创建的句柄。有关更多信息，请参阅创建功能类型的实例。

此示例演示如何运行面部检测功能实例

            

            
NvAR_Run(faceDetectHandle);
        

1.3.8. 销毁功能实例

当不再需要功能实例时，您需要销毁它以释放功能实例在内部分配的资源和内存。

内存缓冲区作为输入提供，并用于保存功能的输出，必须单独释放。

要销毁功能实例，请调用 NvAR_Destroy() 函数，并指定在创建实例时为功能实例创建的句柄。有关更多信息，请参阅创建功能类型的实例。

            

            
NvAR_Destroy(faceDetectHandle);
        

1.4. 在 GPU 或 CPU 缓冲区上处理图像帧

效果滤镜接受图像缓冲区作为 NvCVImage 对象。图像缓冲区可以是 CPU 或 GPU 缓冲区，但出于性能原因，效果滤镜需要 GPU 缓冲区。AR SDK 提供了将图像表示形式转换为 NvCVImage 以及在 CPU 和 GPU 缓冲区之间传输图像的功能。

有关 NvCVImage 的更多信息，请参阅 NvCVImage API 指南。本节概述了 AR SDK 最常用的函数。

1.4.1. 将图像表示形式转换为 NvCVImage 对象

AR SDK 提供了用于将 OpenCV 图像和其他图像表示形式转换为 NvCVImage 对象的函数。每个函数都在现有缓冲区周围放置一个包装器。当调用包装器的析构函数时，包装器会阻止缓冲区被释放。

1.4.1.1. 将 OpenCV 图像转换为 NvCVImage 对象

您可以使用 AR SDK 专门为 RGB OpenCV 图像提供的包装器函数。

• 要为 OpenCV 图像创建 NvCVImage 对象包装器，请使用 NVWrapperForCVMat() 函数。
  复制

  已复制！

              
  
              
  //Allocate source and destination OpenCV images
  cv::Mat srcCVImg(   );
  cv::Mat dstCVImg(...);
   
  // Declare source and destination NvCVImage objects
  NvCVImage srcCPUImg;
  NvCVImage dstCPUImg;
   
  NVWrapperForCVMat(&srcCVImg, &srcCPUImg);
  NVWrapperForCVMat(&dstCVImg, &dstCPUImg);
          

  
  
• 要为 NvCVImage 对象创建 OpenCV 图像包装器，请使用 CVWrapperForNvCVImage() 函数。
  复制

  已复制！

              
  
              
  // Allocate source and destination NvCVImage objects
  NvCVImage srcCPUImg(...);
  NvCVImage dstCPUImg(...);
   
  //Declare source and destination OpenCV images
  cv::Mat srcCVImg;
  cv::Mat dstCVImg;
   
  CVWrapperForNvCVImage (&srcCPUImg, &srcCVImg);
  CVWrapperForNvCVImage (&dstCPUImg, &dstCVImg);
          

  
  

1.4.1.2. 将其他图像表示形式转换为 NvCVImage 对象

要转换其他图像表示形式，请调用 NvCVImage_Init() 函数以在现有缓冲区 (srcPixelBuffer) 周围放置一个包装器。

            

            
NvCVImage src_gpu;
vfxErr = NvCVImage_Init(&src_gpu, 640, 480, 1920, srcPixelBuffer, NVCV_BGR, NVCV_U8, NVCV_INTERLEAVED, NVCV_GPU);
NvCVImage src_cpu;
vfxErr = NvCVImage_Init(&src_cpu, 640, 480, 1920, srcPixelBuffer, NVCV_BGR, NVCV_U8, NVCV_INTERLEAVED, NVCV_CPU);
        

1.4.1.3. 将来自 NvDecoder 的解码帧转换为 NvCVImage 对象

要将来自 NVDecoder 的解码帧转换为 NvCVImage 对象，请调用 NvCVImage_Transfer() 函数以转换由 NvDecoder 提供的解码帧，从解码像素格式转换为 AR SDK 功能所需的格式。

以下示例显示了从 NV12 转换为 BGRA 像素格式的解码帧。

            

            
NvCVImage decoded_frame, BGRA_frame, stagingBuffer;
NvDecoder dec;
 
//Initialize decoder...
//Assuming dec.GetOutputFormat() == cudaVideoSurfaceFormat_NV12
 
//Initialize memory for decoded frame
NvCVImage_Init(&decoded_frame, dec.GetWidth(), dec.GetHeight(), dec.GetDeviceFramePitch(), NULL, NVCV_YUV420, NVCV_U8, NVCV_NV12, NVCV_GPU, 1);
decoded_frame.colorSpace = NVCV_709 | NVCV_VIDEO_RANGE | NVCV_CHROMA_COSITED;
 
//Allocate memory for BGRA frame, and set alpha opaque
NvCVImage_Alloc(&BGRA_frame, dec.GetWidth(), dec.GetHeight(), NVCV_BGRA, NVCV_U8, NVCV_CHUNKY, NVCV_GPU, 1);
cudaMemset(BGRA_frame.pixels, -1, BGRA_frame.pitch * BGRA_frame.height);
 
decoded_frame.pixels = (void*)dec.GetFrame();
 
//Convert from decoded frame format(NV12) to desired format(BGRA)
NvCVImage_Transfer(&decoded_frame, &BGRA_frame, 1.f, stream, & stagingBuffer);
        

1.4.1.4. 将 NvCVImage 对象转换为可由 NvEncoder 编码的缓冲区

要将 NvCVImage 转换为通过 NvEncoder 进行编码时使用的像素格式，如有必要，请调用 NvCVImage_Transfer() 函数。

以下示例显示了以 BGRA 像素格式编码的帧。

            

            
convert-nvcvimage-obj-buffer-encoded-nvencoderThe following sample shows a frame that is encoded in the BGRA pixel format.
//BGRA frame is 4-channel, u8 buffer residing on the GPU
NvCVImage BGRA_frame;
NvCVImage_Alloc(&BGRA_frame, dec.GetWidth(), dec.GetHeight(), NVCV_BGRA, NVCV_U8, NVCV_CHUNKY, NVCV_GPU, 1);
//Initialize encoder with a BGRA output pixel format
using NvEncCudaPtr = std::unique_ptr<NvEncoderCuda, std::function<void(NvEncoderCuda*)>>;
NvEncCudaPtr pEnc(new NvEncoderCuda(cuContext, dec.GetWidth(), dec.GetHeight(), NV_ENC_BUFFER_FORMAT_ARGB));
pEnc->CreateEncoder(&initializeParams);
//...
 
std::vector<std::vector<uint8_t>> vPacket;
//Get the address of the next input frame from the encoder
const NvEncInputFrame* encoderInputFrame = pEnc->GetNextInputFrame();
 
 
//Copy the pixel data from BGRA_frame into the input frame address obtained above
NvEncoderCuda::CopyToDeviceFrame(cuContext,
                        BGRA_frame.pixels,
            	        BGRA_frame.pitch,
                        (CUdeviceptr)encoderInputFrame->inputPtr,
                        encoderInputFrame->pitch,
                        pEnc->GetEncodeWidth(),
                        pEnc->GetEncodeHeight(),
             	       CU_MEMORYTYPE_DEVICE,
                        encoderInputFrame->bufferFormat,
                        encoderInputFrame->chromaOffsets,
                        encoderInputFrame->numChromaPlanes);
pEnc->EncodeFrame(vPacket);
        

1.4.2. 分配 NvCVImage 对象缓冲区

您可以使用 NvCVImage 分配构造函数或图像函数为 NvCVImage 对象分配缓冲区。在这两种方式中，当图像超出作用域时，缓冲区都会被析构函数自动释放。

1.4.2.1. 使用 NvCVImage 分配构造函数分配缓冲区

NvCVImage 分配构造函数创建一个已分配内存并已初始化的对象。有关更多信息，请参阅分配构造函数。
分配构造函数的最后三个可选参数决定了生成的 NvCVImage 对象的属性：

• 像素组织决定了蓝色、绿色和红色是在单独的平面中还是交错排列。
• 内存类型决定了缓冲区驻留在 GPU 还是 CPU 上。
• 字节对齐决定了连续扫描线之间的间隙。

以下示例展示了如何使用分配构造函数的最后三个可选参数来确定 NvCVImage 对象的属性。

• 此示例创建一个对象，而不设置分配构造函数的最后三个可选参数。在此对象中，蓝色、绿色和红色分量在每个像素中交错排列，缓冲区驻留在 CPU 上，并且字节对齐是默认对齐。
  复制

  已复制！

              
  
              
  NvCVImage cpuSrc(
    srcWidth,
    srcHeight,
    NVCV_BGR,
    NVCV_U8
  );
          

  
  
• 此示例创建一个对象，其像素组织、内存类型和字节对齐与上一个示例相同，方法是显式设置最后三个可选参数。与上一个示例一样，蓝色、绿色和红色分量在每个像素中交错排列，缓冲区驻留在 CPU 上，并且字节对齐是默认值，即针对最大性能进行了优化。
  复制

  已复制！

              
  
              
  NvCVImage src(
    srcWidth,
    srcHeight,
    NVCV_BGR,
    NVCV_U8,
    NVCV_INTERLEAVED,
    NVCV_CPU,
    0
  );
          

  
  
• 此示例创建一个对象，其中蓝色、绿色和红色分量在单独的平面中，缓冲区驻留在 GPU 上，并且字节对齐确保一个扫描线和下一个扫描线之间不存在间隙。
  复制

  已复制！

              
  
              
  NvCVImage gpuSrc(
    srcWidth,
    srcHeight,
    NVCV_BGR,
    NVCV_U8,
    NVCV_PLANAR,
    NVCV_GPU,
    1
  );
          

  
  

1.4.2.2. 使用图像函数分配缓冲区

通过声明一个空图像，您可以延迟缓冲区分配。

1. 声明一个空的 NvCVImage 对象。
   复制

   已复制！

               
   
               
   NvCVImage xfr;
           

2. 为图像分配或重新分配缓冲区。
   • 要分配缓冲区，请调用 NvCVImage_Alloc() 函数。

     当图像是状态结构的一部分时，以此方式分配缓冲区，在这种情况下，您将稍后才知道图像的大小。

   • 要重新分配缓冲区，请调用 NvCVImage_Realloc()。

     此函数检查是否已分配缓冲区，并在释放缓冲区并调用 NvCVImage_Alloc() 之前，如果缓冲区足够大，则会重塑缓冲区。

1.4.3. 在 CPU 和 GPU 缓冲区之间传输图像

如果输入和输出图像缓冲区的内存类型不同，则应用程序可以在 CPU 和 GPU 缓冲区之间传输图像。

1.4.3.1. 将输入图像从 CPU 缓冲区传输到 GPU 缓冲区

以下是将输入图像从 CPU 缓冲区传输到 GPU 缓冲区的步骤。

1. 创建一个 NvCVImage 对象，用作具有与源 CPU 缓冲区相同尺寸和格式的暂存 GPU 缓冲区。
   复制

   已复制！

               
   
               
   NvCVImage srcGpuPlanar(inWidth, inHeight, NVCV_BGR, NVCV_F32, NVCV_PLANAR, NVCV_GPU,1)
           

   
   
2. 通过以下方式之一创建暂存缓冲区：
   • 为避免在视频管道中分配内存，请创建一个 GPU 缓冲区，该缓冲区具有与视频效果滤镜输入所需的尺寸和格式相同的尺寸和格式。
     复制

     已复制！

                 
     
                 
     NvCVImage srcGpuStaging(inWidth, inHeight, srcCPUImg.pixelFormat, srcCPUImg.componentType, srcCPUImg.planar, NVCV_GPU)
             

     
     
   • 为了简化您的应用程序代码，请声明一个空的暂存缓冲区。
     复制

     已复制！

                 
     
                 
     NvCVImage srcGpuStaging;
             

     
     

     将根据需要分配或重新分配适当的缓冲区。

3. 调用 NvCVImage_Transfer() 函数，以通过暂存 GPU 缓冲区将源 CPU 缓冲区内容复制到最终 GPU 缓冲区中。
   复制

   已复制！

               
   
               
   //Read the image into srcCPUImg
   NvCVImage_Transfer(&srcCPUImg, &srcGPUPlanar, 1.0f, stream, &srcGPUStaging)
           

   
   

1.4.3.2. 将输出图像从 GPU 缓冲区传输到 CPU 缓冲区

以下是将输出图像从 CPU 缓冲区传输到 GPU 缓冲区的步骤。

1. 创建一个 NvCVImage 对象，用作具有与目标 CPU 缓冲区相同尺寸和格式的暂存 GPU 缓冲区。
   复制

   已复制！

               
   
               
   NvCVImage dstGpuPlanar(outWidth, outHeight, NVCV_BGR, NVCV_F32, NVCV_PLANAR, NVCV_GPU, 1)
           

   
   

   有关 NvCVImage 的更多信息，请参阅NvCVImage API 指南。

2. 通过以下方式之一创建暂存缓冲区：
   • 为避免在视频管道中分配内存，请创建一个 GPU 缓冲区，该缓冲区具有与视频效果滤镜输出的尺寸和格式相同的尺寸和格式。
     复制

     已复制！

                 
     
                 
     NvCVImage dstGpuStaging(outWidth, outHeight, dstCPUImg.pixelFormat, dstCPUImg.componentType, dstCPUImg.planar, NVCV_GPU)
             

   • 为了简化您的应用程序代码，请声明一个空的暂存缓冲区
     复制

     已复制！

                 
     
                 
     NvCVImage dstGpuStaging;
             

   将根据需要分配适当大小的缓冲区。

3. 调用 NvCVImage_Transfer() 函数，以通过暂存 GPU 缓冲区将 GPU 缓冲区内容复制到目标 CPU 缓冲区中。
   复制

   已复制！

               
   
               
   //Retrieve the image from the GPU to CPU, perhaps with conversion.
   NvCVImage_Transfer(&dstGpuPlanar, &dstCPUImg, 1.0f, stream, &dstGpuStaging);
           

   
   

1.5. AR SDK 功能的属性列表

本节提供 AR SDK 中功能的属性及其值。

1.5.1. 人脸检测和跟踪属性值

下表列出了人脸检测和跟踪的配置、输入和输出属性的值。

1.5.2. Landmark 跟踪属性值

下表列出了 Landmark 跟踪的配置、输入和输出属性的值。

1.5.3. 人脸 3D 网格跟踪属性值

下表列出了人脸 3D 网格跟踪的配置、输入和输出属性的值。

1.5.4. 眼神交流属性值

下表列出了注视重定向的值。

1.5.5. 身体检测属性值

下表列出了身体检测跟踪的配置、输入和输出属性的值。

1.5.6. 3D 身体姿态关键点跟踪属性值

下表列出了 3D 身体姿态关键点跟踪的配置、输入和输出属性的值。

1.5.7. 面部表情估计属性值

下表列出了面部表情估计的配置、输入和输出属性的值。

1.6. 使用 AR 功能

本节提供有关如何使用 AR 功能的信息。

1.6.1. 人脸检测和跟踪

本节提供有关如何使用人脸检测和跟踪功能的信息。

1.6.1.1. 静态帧（图像）的人脸检测

要获取检测到的边界框，您可以显式实例化并运行人脸检测功能，如下所示，该功能将图像缓冲区作为输入。

此示例使用输入图像缓冲区和输出内存运行人脸检测 AR 功能，以保存边界框

            

            
//Set input image buffer
NvAR_SetObject(faceDetectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
//Set output memory for bounding boxes
NvAR_BBoxes = output_boxes{};
output_bboxes.boxes = new NvAR_Rect[25];
output_bboxes.max_boxes = 25;
NvAR_SetObject(faceDetectHandle, NvAR_Parameter_Output(BoundingBoxes), &output_bboxes, sizeof(NvAR_BBoxes));
 //OPTIONAL – Set memory for bounding box confidence values if desired
 NvAR_Run(faceDetectHandle);
        

1.6.1.2. 时序帧（视频）的人脸跟踪

如果启用了 Temporal，例如当您处理视频帧而不是图像时，则仅返回一张人脸。第一帧显示最大的人脸，随后在后续帧中跟踪此人脸。

但是，显式调用人脸检测功能并不是获取表示检测到的人脸的边界框的唯一方法。有关如何使用地标检测或人脸 3D 重建 AR 功能并返回人脸边界框的更多信息，请参阅 地标检测和跟踪 和 人脸 3D 网格和跟踪。

1.6.2. 地标检测和跟踪

本节提供有关如何使用地标检测和跟踪功能的信息。

1.6.2.1. 静态帧（图像）的地标检测

通常，地标检测功能的输入是输入图像和一批（最多 8 个）边界框。目前，最大值为 1。这些框表示图像中包含您要运行地标检测的人脸的区域。

此示例在从人脸检测获取边界框后运行地标检测 AR 功能

            

            
//Set input image buffer
NvAR_SetObject(landmarkDetectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
 
//Pass output bounding boxes from face detection as an input on which //landmark detection is to be run
NvAR_SetObject(landmarkDetectHandle, NvAR_Parameter_Input(BoundingBoxes), &output_bboxes, sizeof(NvAR_BBoxes));
 
//Set landmark detection mode: Performance[0] (Default) or Quality[1]
unsigned int mode = 0;	// Choose performance mode
NvAR_SetU32(landmarkDetectHandle, NvAR_Parameter_Config(Mode), mode);

//Set output buffer to hold detected facial keypoints
std::vector<NvAR_Point2f> facial_landmarks;
facial_landmarks.assign(OUTPUT_SIZE_KPTS, {0.f, 0.f});
NvAR_SetObject(landmarkDetectHandle, NvAR_Parameter_Output(Landmarks), facial_landmarks.data(),sizeof(NvAR_Point2f));
 NvAR_Run(landmarkDetectHandle);
        

1.6.2.2. 地标检测的替代用法

如 地标跟踪属性值 中地标跟踪的配置属性表所述，地标检测 AR 功能支持一些可选参数，这些参数确定了功能的运行方式。

如果未将边界框作为输入提供给地标检测 AR 功能，则会自动在输入图像上运行人脸检测，并选择最大的人脸边界框来运行地标检测。

如果 BoundingBoxes 设置为输出属性，则该属性将填充包含运行地标检测的人脸的所选边界框。地标不是可选属性，要显式运行此功能，必须使用提供的输出缓冲区设置此属性。

1.6.2.3. 时序帧（视频）的地标跟踪

此外，如果启用了 Temporal，例如当您处理视频流并且显式运行人脸检测时，则仅支持一个边界框作为地标检测的输入。

当未显式运行人脸检测时，通过提供输入图像而不是边界框，将自动选择检测到的最大人脸。然后，跨时间相关的帧将跟踪检测到的人脸和地标以进行优化。

此示例使用地标检测 AR 功能直接从图像中获取地标，而无需首先显式运行人脸检测

            

            
//Set input image buffer
NvAR_SetObject(landmarkDetectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
 
//Set output memory for landmarks
std::vector<NvAR_Point2f> facial_landmarks;
facial_landmarks.assign(batchSize * OUTPUT_SIZE_KPTS, {0.f, 0.f});
NvAR_SetObject(landmarkDetectHandle, NvAR_Parameter_Output(Landmarks), facial_landmarks.data(),sizeof(NvAR_Point2f));
 
//Set landmark detection mode: Performance[0] (Default) or Quality[1]
unsigned int mode = 0;	// Choose performance mode
NvAR_SetU32(landmarkDetectHandle, NvAR_Parameter_Config(Mode), mode);
 
//OPTIONAL – Set output memory for bounding box if desired
NvAr_BBoxes = output_boxes{};
output_bboxes.boxes = new NvAR_Rect[25];
output_bboxes.max_boxes = 25;
NvAR_SetObject(landmarkDetectHandle, NvAR_Parameter_Output(BoundingBoxes), &output_bboxes, sizeof(NvAr_BBoxes));
 
//OPTIONAL – Set output memory for pose, landmark confidence, or even bounding box confidence if desired
 
NvAR_Run(landmarkDetectHandle);
        

1.6.3. 人脸 3D 网格和跟踪

本节提供有关如何使用人脸 3D 网格和跟踪功能的信息。

1.6.3.1. 静态帧（图像）的人脸 3D 网格

通常，人脸 3D 网格功能的输入是输入图像和一组检测到的地标点，这些地标点对应于我们要运行 3D 重建的人脸。

这是此功能的典型用法，其中来自地标检测功能的检测到的人脸关键点作为输入传递到此功能

            

            
//Set facial keypoints from Landmark Detection as an input
NvAR_SetObject(faceFitHandle, NvAR_Parameter_Input(Landmarks), facial_landmarks.data(),sizeof(NvAR_Point2f));
//Set output memory for face mesh
NvAR_FaceMesh face_mesh = new NvAR_FaceMesh();
face_mesh->vertices = new NvAR_Vector3f[FACE_MODEL_NUM_VERTICES];
face_mesh->tvi = new NvAR_Vector3u16[FACE_MODEL_NUM_INDICES];
NvAR_SetObject(faceFitHandle, NvAR_Parameter_Output(FaceMesh), face_mesh, sizeof(NvAR_FaceMesh));
//Set output memory for rendering parameters
NvAR_RenderingParams rendering_params = new NvAR_RenderingParams();
NvAR_SetObject(faceFitHandle, NvAR_Parameter_Output(RenderingParams), rendering_params, sizeof(NvAR_RenderingParams));
 NvAR_Run(faceFitHandle);
        

1.6.3.2. 人脸 3D 网格功能的替代用法

与地标检测功能的替代用法类似，人脸 3D 网格 AR 功能可用于确定检测到的人脸边界框、人脸关键点以及 3D 人脸网格及其渲染参数。

如果提供输入图像而不是人脸的关键点，则会自动检测人脸和人脸关键点，并将其用于运行人脸网格拟合。以这种方式运行时，如果将 BoundingBoxes 和/或 Landmarks 设置为此功能的可选输出属性，则这些属性将分别填充包含人脸的边界框和检测到的人脸关键点。

FaceMesh 和 RenderingParams 不是此功能的可选属性，要运行该功能，必须使用用户提供的输出缓冲区设置这些属性。

此外，如果此功能在未提供人脸关键点作为输入的情况下运行，则 ModelDir 配置参数指向的路径还必须包含人脸和地标检测 TRT 包文件。或者，可以为这些功能设置 CUDAStream 和 Temporal 标志。

1.6.3.3. 时序帧（视频）的人脸 3D 网格跟踪

如果设置了 Temporal 标志并且在内部运行人脸和地标检测，则将针对时间相关的帧优化这些功能

这意味着将在帧之间跟踪人脸和人脸关键点，并且如果请求作为输出，则仅返回一个边界框。如果显式调用地标检测和/或人脸检测功能，则人脸 3D 网格功能不支持 Temporal 标志。在这种情况下，您将必须直接向这些功能提供标志。

此示例使用网格跟踪 AR 功能直接从图像中获取人脸网格，而无需显式运行地标检测或人脸检测

            

            
//Set input image buffer instead of providing facial keypoints
NvAR_SetObject(faceFitHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
 
//Set output memory for face mesh
NvAR_FaceMesh face_mesh = new NvAR_FaceMesh();
unsigned int n;
err = NvAR_GetU32(faceFitHandle, NvAR_Parameter_Config(VertexCount), &n);
face_mesh->num_vertices = n;
err = NvAR_GetU32(faceFitHandle, NvAR_Parameter_Config(TriangleCount), &n);
face_mesh->num_triangles = n;
face_mesh->vertices = new NvAR_Vector3f[face_mesh->num_vertices];
face_mesh->tvi = new NvAR_Vector3u16[face_mesh->num_triangles];
NvAR_SetObject(faceFitHandle, NvAR_Parameter_Output(FaceMesh), face_mesh, sizeof(NvAR_FaceMesh));
 
//Set output memory for rendering parameters
NvAR_RenderingParams rendering_params = new NvAR_RenderingParams();
NvAR_SetObject(faceFitHandle, NvAR_Parameter_Output(RenderingParams), rendering_params, sizeof(NvAR_RenderingParams));
 
//OPTIONAL - Set facial keypoints as an output
NvAR_SetObject(faceFitHandle, NvAR_Parameter_Output(Landmarks), facial_landmarks.data(),sizeof(NvAR_Point2f));
 
//OPTIONAL – Set output memory for bounding boxes, or other parameters, such as pose, bounding box/landmarks confidence, etc.
 
NvAR_Run(faceFitHandle);
        

1.6.4. 眼神交流

此功能从使用地标提取的眼部贴片估计人的目光，并将眼睛重定向，使人在允许的眼睛和头部角度范围内看向相机。

该功能还支持一种模式，可以在不重定向的情况下获得估计值。眼神交流功能可以通过使用 GazeRedirection 功能 ID 来调用。眼神交流功能具有以下选项：

• 注视估计
• 注视重定向

在此版本中，仅支持帧中一张人脸的注视估计和重定向。

1.6.4.1. 注视估计

注视估计需要人脸检测和地标作为输入。注视估计器的输入是输入图像缓冲区以及用于保存人脸地标和置信度分数的缓冲区。注视估计的输出是以弧度为单位的注视向量（俯仰角、偏航角）值。需要将浮点数组设置为输出缓冲区以保存估计的注视。必须将 GazeRedirect 参数设置为 false。

此示例使用输入图像缓冲区和输出内存运行注视估计，以保存估计的注视向量

            

            
bool bGazeRedirect=false
NvAR_SetU32(gazeRedirectHandle, NvAR_Parameter_Config(GazeRedirect), bGazeRedirect);
//Set input image buffer
NvAR_SetObject(gazeRedirectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
//Set output memory for gaze vector
float gaze_angles_vector[2];
NvvAR_SetF32Array(gazeRedirectHandle, NvAR_Parameter_Output(OutputGazeVector), gaze_angles_vector, batchSize * 2);
 
//OPTIONAL – Set output memory for landmarks, head pose, head translation and gaze direction if desired
 
std::vector<NvAR_Point2f> facial_landmarks;
facial_landmarks.assign(batchSize * OUTPUT_SIZE_KPTS, {0.f, 0.f});
NvAR_SetObject(gazeRedirectHandle, NvAR_Parameter_Output(Landmarks), facial_landmarks.data(),sizeof(NvAR_Point2f));
 
NvAR_Quaternion head_pose;
NvAR_SetObject(gazeRedirectHandle, NvAR_Parameter_Output(HeadPose), &head_pose, sizeof(NvAR_Quaternion));
 
float head_translation[3] = {0.f};
NvAR_SetF32Array(gazeRedirectHandle, NvAR_Parameter_Output(OutputHeadTranslation), head_translation,
                           batchSize * 3); 
 
NvAR_Run(gazeRedirectHandle);
        

1.6.4.2. 注视重定向

注视重定向采用与注视估计相同的输入。除了注视估计的输出之外，为了存储注视重定向图像，还需要设置与输入图像缓冲区大小相同的输出图像缓冲区。

注视将被重定向到在一定范围的注视角度和头部姿势内看向相机。在此范围之外，该功能将脱离。头部姿势、头部平移和注视方向可以有选择地设置为输出。必须将 GazeRedirect 参数设置为 true。

            

            
bool bGazeRedirect=true;
NvAR_SetU32(gazeRedirectHandle, NvAR_Parameter_Config(GazeRedirect), bGazeRedirect);
//Set input image buffer
NvAR_SetObject(gazeRedirectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
//Set output memory for gaze vector
float gaze_angles_vector[2];
NvvAR_SetF32Array(gazeRedirectHandle, NvAR_Parameter_Output(OutputGazeVector), gaze_angles_vector, batchSize * 2);
//Set output image buffer
NvAR_SetObject(gazeRedirectHandle, NvAR_Parameter_Output(Image), &outputImageBuffer, sizeof(NvCVImage));
NvAR_Run(gazeRedirectHandle);
        

1.6.5. 3D 身体姿势跟踪

此功能依赖于时间信息来跟踪场景中的人物，其中来自上一帧的关键点信息用于估计下一帧的关键点。

3D 身体姿势跟踪包括以下部分：

• 身体检测
• 3D 关键点检测

在此版本中，我们仅支持帧中的一个人，并且当全身（从头到脚）可见时。如果身体的一部分（例如手臂或脚）被遮挡/截断，该功能仍然有效。

1.6.5.1. 静态帧（图像）的 3D 身体姿势跟踪

您可以获取封装场景中人物的边界框。要获取检测到的边界框，您可以显式实例化并运行身体检测，如以下示例所示，并将图像缓冲区作为输入传递。

• 此示例使用输入图像缓冲区和输出内存运行身体检测，以保存边界框
  复制

  已复制！

              
  
              
  //Set input image buffer
  NvAR_SetObject(bodyDetectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
   //Set output memory for bounding boxes
   
  NvAR_BBoxes = output_boxes{};
  output_bboxes.boxes = new NvAR_Rect[25];
  output_bboxes.max_boxes = 25;
  NvAR_SetObject(bodyDetectHandle, NvAR_Parameter_Output(BoundingBoxes), &output_bboxes, sizeof(NvAR_BBoxes));
   
  //OPTIONAL – Set memory for bounding box confidence values if desired
   
  NvAR_Run(bodyDetectHandle);
          

• 3D 身体关键点检测的输入是输入图像。它输出 2D 关键点、3D 关键点、关键点置信度分数和封装人物的边界框。此示例运行 3D 身体姿势检测 AR 功能
  复制

  已复制！

              
  
              
  //Set input image buffer
  NvAR_SetObject(keypointDetectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
   
  //Pass output bounding boxes from body detection as an input on which //landmark detection is to be run
  NvAR_SetObject(keypointDetectHandle, NvAR_Parameter_Input(BoundingBoxes), &output_bboxes, sizeof(NvAR_BBoxes));
   
  //Set output buffer to hold detected keypoints
  std::vector<NvAR_Point2f> keypoints;
  std::vector<NvAR_Point3f> keypoints3D;
  std::vector<NvAR_Point3f> jointAngles;
  std::vector<float> keypoints_confidence;
   
  // Get the number of keypoints
  unsigned int numKeyPoints;
  NvAR_GetU32(keyPointDetectHandle, NvAR_Parameter_Config(NumKeyPoints), &numKeyPoints);
   
  keypoints.assign(batchSize * numKeyPoints , {0.f, 0.f});
  keypoints3D.assign(batchSize * numKeyPoints , {0.f, 0.f, 0.f});
  jointAngles.assign(batchSize * numKeyPoints , {0.f, 0.f, 0.f});
  NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(KeyPoints), keypoints.data(), sizeof(NvAR_Point2f));
  NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(KeyPoints3D), keypoints3D.data(), sizeof(NvAR_Point3f));
  NvAR_SetF32Array(keyPointDetectHandle, NvAR_Parameter_Output(KeyPointsConfidence), keypoints_confidence.data(), batchSize * numKeyPoints);
  NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(JointAngles), jointAngles.data(), sizeof(NvAR_Point3f));
   
  //Set output memory for bounding boxes
  NvAR_BBoxes = output_boxes{};
  output_bboxes.boxes = new NvAR_Rect[25];
  output_bboxes.max_boxes = 25;
  NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(BoundingBoxes), &output_bboxes, sizeof(NvAR_BBoxes));
   
  NvAR_Run(keyPointDetectHandle);
          

  
  

1.6.5.2. 时序帧（视频）的 3D 身体姿势跟踪

该功能依赖于时间信息来跟踪场景中的人物。来自上一帧的关键点信息用于估计下一帧的关键点。

此示例使用 3D 身体姿势跟踪 AR 功能直接从图像中获取 3D 身体姿势关键点

            

            
//Set input image buffer
NvAR_SetObject(keypointDetectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
 
//Pass output bounding boxes from body detection as an input on which //landmark detection is to be run
NvAR_SetObject(keypointDetectHandle, NvAR_Parameter_Input(BoundingBoxes), &output_bboxes, sizeof(NvAR_BBoxes));
 
//Set output buffer to hold detected keypoints
std::vector<NvAR_Point2f> keypoints;
std::vector<NvAR_Point3f> keypoints3D;
std::vector<NvAR_Point3f> jointAngles;
std::vector<float> keypoints_confidence;
 
// Get the number of keypoints
unsigned int numKeyPoints;
NvAR_GetU32(keyPointDetectHandle, NvAR_Parameter_Config(NumKeyPoints), &numKeyPoints);
 
keypoints.assign(batchSize * numKeyPoints , {0.f, 0.f});
keypoints3D.assign(batchSize * numKeyPoints , {0.f, 0.f, 0.f});
jointAngles.assign(batchSize * numKeyPoints , {0.f, 0.f, 0.f});
NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(KeyPoints), keypoints.data(), sizeof(NvAR_Point2f));
NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(KeyPoints3D), keypoints3D.data(), sizeof(NvAR_Point3f));
NvAR_SetF32Array(keyPointDetectHandle, NvAR_Parameter_Output(KeyPointsConfidence), keypoints_confidence.data(), batchSize * numKeyPoints);
NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(JointAngles), jointAngles.data(), sizeof(NvAR_Point3f));
 
//Set output memory for bounding boxes
NvAR_BBoxes = output_boxes{};
output_bboxes.boxes = new NvAR_Rect[25];
output_bboxes.max_boxes = 25;
NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(BoundingBoxes), &output_bboxes, sizeof(NvAR_BBoxes));
 
NvAR_Run(keyPointDetectHandle);
        

1.6.5.3. 3D 身体姿势跟踪的多人跟踪（仅限 Windows）

该功能依赖于时间信息来跟踪场景中的人物。来自上一帧的关键点信息用于估计下一帧的关键点。

该功能提供以下方式跟踪多人的能力：

• 在不同帧的场景中。
• 当他们离开场景并再次进入场景时。
• 当他们被物体或另一个人完全遮挡并重新出现时（使用阴影跟踪年龄控制）。

• 阴影跟踪年龄

  此选项表示即使目标未与检测器对象关联，仍在后台跟踪目标的时间段。当目标在时间帧内未与检测器对象关联时，阴影跟踪年龄（目标的内部变量）会递增。在目标与检测器对象关联后，阴影跟踪年龄将重置为零。当目标年龄达到阴影跟踪年龄时，目标将被丢弃并且不再被跟踪。这以帧数为单位进行测量，默认值为 90。

• 试用期年龄

  此选项是试用期的长度。在对象达到此年龄后，它被认为是有效的并被分配一个 ID。这将有助于消除误报，其中仅在少数帧中检测到虚假对象。这以帧数为单位进行测量，默认值为 10。

• 跟踪的最大目标数

  此选项是要跟踪的最大目标数，它可以由帧中处于活动状态的目标和处于阴影跟踪模式的目标组成。当您选择此值时，请记住活动和非活动目标。最小值为 1，默认值为 30。

此示例使用 3D 身体姿势跟踪 AR 功能启用多人跟踪并获取每个人的跟踪 ID

            

            
//Set input image buffer
NvAR_SetObject(keypointDetectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage)); 
// Enable Multi-Person Tracking
NvAR_SetU32(keyPointDetectHandle, NvAR_Parameter_Config(TrackPeople), bEnablePeopleTracking);
// Set Shadow Tracking Age 
NvAR_SetU32(keyPointDetectHandle, NvAR_Parameter_Config(ShadowTrackingAge), shadowTrackingAge);
// Set Probation Age 
NvAR_SetU32(keyPointDetectHandle, NvAR_Parameter_Config(ProbationAge), probationAge);
// Set Maximum Targets to be tracked 
NvAR_SetU32(keyPointDetectHandle, NvAR_Parameter_Config(MaxTargetsTracked), maxTargetsTracked);
//Set output buffer to hold detected keypoints
std::vector<NvAR_Point2f> keypoints;
std::vector<NvAR_Point3f> keypoints3D;
std::vector<NvAR_Point3f> jointAngles;
std::vector<float> keypoints_confidence;
// Get the number of keypoints
unsigned int numKeyPoints;
NvAR_GetU32(keyPointDetectHandle, NvAR_Parameter_Config(NumKeyPoints), &numKeyPoints);
keypoints.assign(batchSize * numKeyPoints , {0.f, 0.f});
keypoints3D.assign(batchSize * numKeyPoints , {0.f, 0.f, 0.f});
jointAngles.assign(batchSize * numKeyPoints , {0.f, 0.f, 0.f});
NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(KeyPoints), keypoints.data(), sizeof(NvAR_Point2f));
NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(KeyPoints3D), keypoints3D.data(), sizeof(NvAR_Point3f));
NvAR_SetF32Array(keyPointDetectHandle, NvAR_Parameter_Output(KeyPointsConfidence), keypoints_confidence.data(), batchSize * numKeyPoints);
NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(JointAngles), jointAngles.data(), sizeof(NvAR_Point3f));
//Set output memory for tracking bounding boxes
NvAR_TrackingBBoxes output_tracking_bboxes{};
std::vector<NvAR_TrackingBBox> output_tracking_bbox_data;
output_tracking_bbox_data.assign(maxTargetsTracked, { 0.f, 0.f, 0.f, 0.f, 0 });
output_tracking_bboxes.boxes = output_tracking_bbox_data.data();
output_tracking_bboxes.max_boxes = (uint8_t)output_tracking_bbox_size;

NvAR_SetObject(keyPointDetectHandle, NvAR_Parameter_Output(TrackingBoundingBoxes), &output_tracking_bboxes, sizeof(NvAR_TrackingBBoxes));
NvAR_Run(keyPointDetectHandle);
        

1.6.6. 面部表情估计

本节提供有关如何使用面部表情估计功能的信息。

1.6.6.1. 静态帧（图像）的面部表情估计

通常，面部表情估计功能的输入是输入图像和一组检测到的地标点，这些地标点对应于我们要估计面部表情系数的人脸。

这是此功能的典型用法，其中来自地标检测功能的检测到的人脸关键点作为输入传递到此功能

            

            
//Set facial keypoints from Landmark Detection as an input
err = NvAR_SetObject(faceExpressionHandle, NvAR_Parameter_Input(Landmarks), facial_landmarks.data(), sizeof(NvAR_Point2f));
 
//Set output memory for expression coefficients
unsigned int expressionCount;
err = NvAR_GetU32(faceExpressionHandle, NvAR_Parameter_Config(ExpressionCount), &expressionCount);
float expressionCoeffs = new float[expressionCount];
err = NvAR_SetF32Array(faceExpressionHandle,  NvAR_Parameter_Output(ExpressionCoefficients), expressionCoeffs, expressionCount);
 
//Set output memory for pose rotation quaternion
NvAR_Quaternion pose = new NvAR_Quaternion();
err = NvAR_SetObject(faceExpressionHandle, NvAR_Parameter_Output(Pose), pose, sizeof(NvAR_Quaternion));
 
//OPTIONAL – Set output memory for bounding boxes, and their confidences if desired
err = NvAR_Run(faceExpressionHandle);
        

1.6.6.2. 面部表情估计功能的替代用法

与地标检测功能和人脸 3D 网格功能的替代用法类似，面部表情估计功能可用于确定检测到的人脸边界框、人脸关键点以及 3D 人脸网格及其渲染参数。

如果提供输入图像而不是人脸的关键点，则会自动检测人脸和人脸关键点，并将其用于运行表情估计。以这种方式运行时，如果将 BoundingBoxes 和/或 Landmarks 设置为此功能的可选输出属性，则这些属性将分别填充包含人脸的边界框和检测到的人脸关键点。

ExpressionCoefficients 和 Pose 不是此功能的可选属性，要运行该功能，必须使用用户提供的输出缓冲区设置这些属性。

此外，如果此功能在未提供人脸关键点作为输入的情况下运行，则 ModelDir 配置参数指向的路径还必须包含人脸和地标检测 TRT 包文件。或者，可以为这些功能设置 CUDAStream 和 Temporal 标志。

表达式系数可用于驱动化身的表情。

此示例使用面部表情估计功能直接从图像中获取面部表情系数，而无需显式运行地标检测或人脸检测

            

            
//Set input image buffer instead of providing facial keypoints
NvAR_SetObject(faceExpressionHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
 
//Set output memory for expression coefficients
unsigned int expressionCount;
err = NvAR_GetU32(faceExpressionHandle, NvAR_Parameter_Config(ExpressionCount), &expressionCount);
float expressionCoeffs = new float[expressionCount];
err = NvAR_SetF32Array(faceExpressionHandle,  NvAR_Parameter_Output(ExpressionCoefficients), expressionCoeffs, expressionCount);
 
//Set output memory for pose rotation quaternion
NvAR_Quaternion pose = new NvAR_Quaternion();
err = NvAR_SetObject(faceExpressionHandle, NvAR_Parameter_Output(Pose), pose, sizeof(NvAR_Quaternion));
 
//OPTIONAL - Set facial keypoints as an output
NvAR_SetObject(faceExpressionHandle, NvAR_Parameter_Output(Landmarks), facial_landmarks.data(),sizeof(NvAR_Point2f));
 
//OPTIONAL – Set output memory for bounding boxes, or other parameters, such as pose, bounding box/landmarks confidence, etc.
 
NvAR_Run(faceExpressionHandle);
        

1.6.6.3. 时序帧（视频）的面部表情估计跟踪

如果设置了 Temporal 标志并且在内部运行人脸和地标检测，则将针对时间相关的帧优化这些功能。

这意味着将在帧之间跟踪人脸和人脸关键点，并且如果请求作为输出，则仅返回一个边界框。如果显式使用了人脸检测和地标检测功能，则它们需要设置自己的 Temporal 标志，但是，temporal 标志也会通过 NVAR_TEMPORAL_FILTER_FACIAL_EXPRESSIONS、 NVAR_TEMPORAL_FILTER_FACIAL_GAZE 和 NVAR_TEMPORAL_FILTER_ENHANCE_EXPRESSIONS 位影响面部表情估计功能。

1.7. 使用多个 GPU

使用 AR SDK 开发的应用程序可以与多个 GPU 一起使用。默认情况下，SDK 根据当前选定 GPU 的功能确定要使用的 GPU。如果当前选定的 GPU 支持 AR SDK，则 SDK 会使用它。否则，SDK 会选择最佳 GPU。

您可以使用 cudaSetDevice(int whichGPU) 和 cudaGetDevice(int *whichGPU) NVIDIA CUDA® 工具包函数以及 NvAR_SetS32(NULL, NvAR_Parameter_Config(GPU), whichGPU) AR SDK Set 函数来控制在多 GPU 环境中使用哪个 GPU。Set() 调用仅在创建任何效果之前对 AR SDK 调用一次。由于不可能透明地将在一个 GPU 上分配的图像传递到另一个 GPU，因此您必须确保所有 AR 功能都使用相同的 GPU。

            

            
NvCV_Status err;
int chosenGPU = 0; // or whatever GPU you want to use
err = NvAR_SetS32(NULL, NvAR_Parameter_Config(GPU), chosenGPU);
if (NVCV_SUCCESS != err) {
	printf(“Error choosing GPU %d: %s\n”, chosenGPU,
    	    NvCV_GetErrorStringFromCode(err));
}
cudaSetDevice(chosenGPU);
NvCVImage dst = new NvCVImage(…);
NvAR_Handle eff;
err = NvAR_API NvAR_CreateEffect(code, &eff);
…
err = NvAR_API NvAR_Load(eff);
err = NvAR_API NvAR_Run(eff, true);
// switch GPU for other task, then switch back for next frame
        

缓冲区需要分配在选定的 GPU 上，因此在 GPU 上分配图像之前，请调用 cudaSetDevice()。神经网络需要加载到选定的 GPU 上，因此在调用 NvAR_Load() 之前，请将此 GPU 设置为当前设备。

要使用缓冲区和模型，请在调用 NvAR_Run() 之前将 GPU 设备设置为当前设备。之前调用 NvAR_SetS32(NULL, NvAR_Parameter_Config(GPU), whichGPU) 有助于强制执行此要求。

出于性能考虑，切换到适当的 GPU 是应用程序的责任。

1.7.1. 多 GPU 环境中的默认行为

NvAR_Load() 函数在内部调用 cudaGetDevice() 以识别当前选定的 GPU。

该函数检查当前选定 GPU（默认值 0）的计算能力，以确定 GPU 架构是否支持 AR SDK，并完成以下任务之一：

• 如果支持 SDK，则 NvAR_Load() 使用该 GPU。
• 如果不支持 SDK，则 NvAR_Load() 搜索最强大的支持 AR SDK 的 GPU，并调用 cudaSetDevice() 将该 GPU 设置为当前 GPU。

如果您不要求应用程序在多 GPU 环境中使用特定 GPU，则默认行为应该足够。

1.7.2. 在多 GPU 环境中为 AR SDK 处理选择 GPU

您的应用程序可能被设计为仅通过在多 GPU 环境中使用特定 GPU 来执行应用 AR 滤镜的任务。在这种情况下，请确保 AR SDK 不会覆盖您为应用视频效果滤镜而选择的 GPU。

            

            
// Initialization
cudaGetDevice(&beforeGPU);
err = NvAR_Load(eff);
if (NVCV_SUCCESS != err) { printf("Cannot load ARSDK: %s\n",
   NvCV_GetErrorStringFromCode(err)); exit(-1); }
cudaGetDevice(&arsdkGPU);
if (beforeGPU != arsdkGPU) {
  printf("GPU #%d cannot run AR SDK, so GPU #%d was chosen instead\n",
	beforeGPU, arsdkGPU);
}
        

1.7.3. 为不同任务选择不同的 GPU

您的应用程序可能被设计为在多 GPU 环境中执行多项任务，例如，渲染游戏和应用 AR 滤镜。在这种情况下，在调用 NvAR_Load() 之前，为每个任务选择最佳 GPU。

1. 调用 cudaGetDeviceCount() 以确定环境中 GPU 的数量。
   复制

   已复制！

               
   
               
   // Get the number of GPUs cuErr = cudaGetDeviceCount(&deviceCount);
           

   
   
2. 获取每个 GPU 的属性，并通过对循环中的每个 GPU 执行以下操作来确定它是否是每个任务的最佳 GPU：
   1. 调用 cudaSetDevice() 以设置当前 GPU。
   2. 调用 cudaGetDeviceProperties() 以获取当前 GPU 的属性。
   3. 要确定 GPU 是否是每个特定任务的最佳 GPU，请在您的应用程序中使用自定义代码来分析通过 cudaGetDeviceProperties() 检索到的属性。

      此示例使用计算能力来确定是否应分析 GPU 的属性，并确定当前 GPU 是否是应用视频效果滤镜的最佳 GPU。仅当计算能力为 7.5、8.6 或 8.9 时才分析 GPU 的属性，这表示基于 Turing、Ampere 架构或 Ada 架构的 GPU。

      复制

      已复制！

                  
      
                  
      // Loop through the GPUs to get the properties of each GPU and
        //determine if it is the best GPU for each task based on the
        //properties obtained.
        for (int dev = 0; dev < deviceCount; ++dev) {
      	cudaSetDevice(dev);
      	cudaGetDeviceProperties(&deviceProp, dev);
      	if (DeviceIsBestForARSDK(&deviceProp))  gpuARSDK = dev;
      	if (DeviceIsBestForGame(&deviceProp)) gpuGame = dev;
      	...
        }
        cudaSetDevice(gpuARSDK);
        err = NvAR_Set...; // set parameters
        err = NvAR_Load(eff);
              

      
      

3. 在完成应用程序任务的循环中，在执行任务之前为每个任务选择最佳 GPU。
   1. 调用 cudaSetDevice() 以选择任务的 GPU。
   2. 进行执行任务所需的所有函数调用。

      通过这种方式，您只需为每个任务选择一次最佳 GPU，而无需为每个函数调用设置 GPU。

      此示例选择最佳 GPU 来渲染游戏，并使用自定义代码来渲染游戏。然后，它选择最佳 GPU 来应用视频效果滤镜，然后再调用 NvCVImage_Transfer() 和 NvAR_Run() 函数来应用滤镜，从而避免了为每个 AR SDK API 调用保存和恢复 GPU 的需要。

      复制

      已复制！

                  
      
                  
      // Select the best GPU for each task and perform the task.
      
      while (!done) {
        ...
        cudaSetDevice(gpuGame);
        RenderGame();
        cudaSetDevice(gpuARSDK);
        err = NvAR_Run(eff, 1);
        ...
      }
              

      
      

1.7.4. 使用多实例 GPU（仅限 Linux）

使用 AR SDK 开发的应用程序可以部署在受支持设备（例如 NVIDIA DGX™ A100）上的多实例 GPU (MIG) 上。

MIG 允许您将设备划分为最多七个 GPU 实例，每个实例都有单独的流式多处理器、单独的 GPU 内存切片以及通往内存的单独路径。此过程确保一个分区上的应用程序的大量资源使用不会影响在其他分区上运行的应用程序的性能。

要在 MIG 分区上运行应用程序，您无需在应用程序中调用任何其他 SDK API。您可以在调用应用程序期间指定要用于执行的 MIG 实例。您可以使用以下选项之一选择 MIG 实例：

• 使用 CUDA_VISIBLE_DEVICES 环境变量的裸机方法。
• 通过使用 NVIDIA 容器工具包的容器方法。

  MIG 仅在 Linux 上受支持。

有关 MIG 及其用法的更多信息，请参阅 NVIDIA 多实例 GPU 用户指南。

本节提供有关 AR SDK 中 API 的详细信息。

2.1. 结构

AR SDK 中的结构在以下头文件中定义

• nvAR.h
• nvAR_defs.h

nvAR_defs.h 头文件中定义的结构主要是数据类型。

2.1.1. NvAR_BBoxes

以下是有关 NvAR_BBoxes 结构的详细信息。

            

            
struct NvAR_BBoxes {
  NvAR_Rect *boxes;
  uint8_t num_boxes;
  uint8_t max_boxes;
};
        

成员

boxes

类型：NvAR_Rect *

指向用户分配的边界框数组的指针。

num_boxes

类型：uint8_t

数组中边界框的数量。

max_boxes

类型：uint8_t

可以存储在数组中的边界框的最大数量，由用户定义。

备注

此结构作为人脸检测功能的输出返回。

定义在：nvAR_defs.h

2.1.2. NvAR_TrackingBBox

以下是有关 NvAR_TrackingBBox 结构的详细信息。

            

            
struct NvAR_TrackingBBox {
  NvAR_Rect bbox;
  uint16_t tracking_id;
};
        

成员

bbox

类型：NvAR_Rect

用户分配的边界框。

tracking_id

类型：uint16_t

多人跟踪分配给边界框的跟踪 ID。

备注

当启用多人跟踪时，此结构作为身体姿势功能的输出返回。

定义在：nvAR_defs.h

2.1.3. NvAR_TrackingBBoxes

以下是有关 NvAR_TrackingBBoxes 结构的详细信息。

            

            
struct NvAR_TrackingBBoxes {
  NvAR_TrackingBBox *boxes;
  uint8_t num_boxes;
  uint8_t max_boxes;
};
        

成员

boxes

类型：NvAR_TrackingBBox *

指向用户分配的跟踪边界框数组的指针。

num_boxes

类型：uint8_t

数组中边界框的数量。

max_boxes

类型：uint8_t

可以存储在数组中的边界框的最大数量，由用户定义。

备注

当启用多人跟踪时，此结构作为身体姿势功能的输出返回。

定义在：nvAR_defs.h

2.1.4. NvAR_FaceMesh

以下是有关 NvAR_FaceMesh 结构的详细信息。

            

            
struct NvAR_FaceMesh {
  NvAR_Vec3<float> *vertices;
  size_t num_vertices;
  NvAR_Vec3<unsigned short> *tvi;
  size_t num_tri_idx;
};
        

成员

vertices

类型：NvAR_Vec3<float>*

指向表示网格 3D 顶点位置的向量数组的指针。

num_triangles

类型：size_t

网格三角形的数量。

tvi

类型：NvAR_Vec3<unsigned short> *

指向表示网格三角形的顶点索引的向量数组的指针。

num_tri_idx

类型：size_t

网格三角形顶点索引的数量。

备注

此结构作为网格跟踪功能的输出返回。

定义在：nvAR_defs.h

2.1.5. NvAR_Frustum

以下是有关 NvAR_Frustum 结构的详细信息。

            

            
struct NvAR_Frustum {
  float left = -1.0f;
  float right = 1.0f;
  float bottom = -1.0f;
  float top = 1.0f;
};
        

成员

left

类型：float

视锥体左上角的 X 坐标。

right

类型：float

视锥体右下角的 X 坐标。

bottom

类型：float

视锥体右下角的 Y 坐标。

top

类型：float

视锥体左上角的 Y 坐标。

备注

此结构表示正交相机的相机视锥体。因此，它仅包含以像素为单位的左、右、上和下坐标。它不包含近剪切平面或远剪切平面。

定义在：nvAR_defs.h

2.1.6. NvAR_FeatureHandle

以下是有关 NvAR_FeatureHandle 结构的详细信息。

            

            
typedef struct nvAR_Feature *NvAR_FeatureHandle;
        

备注

此类型定义 SDK 定义的功能的句柄。它用于在运行时引用功能（当功能被执行时），并且在不再需要该功能时必须销毁。

定义在：nvAR_defs.h

2.1.7. NvAR_Point2f

以下是有关 NvAR_Point2f 结构的详细信息。

            

            
typedef struct NvAR_Point2f {
  float x, y;
} NvAR_Point2f;
        

成员

x

类型：float

点的 X 坐标，以像素为单位。

y

类型：float

点的 Y 坐标，以像素为单位。

备注

此结构表示 2D 空间中一个点的 X 和 Y 坐标。

定义在：nvAR_defs.h

2.1.8. NvAR_Point3f

以下是有关 NvAR_Point3f 结构的详细信息。

            

            
typedef struct NvAR_Point3f {
  float x, y, z;
} NvAR_Point3f;
        

成员

x

类型：float

点的 X 坐标，以像素为单位。

y

类型：float

点的 Y 坐标，以像素为单位。

z

类型：float

点的 Z 坐标，以像素为单位。

备注

此结构表示 3D 空间中一个点的 X、Y、Z 坐标。

定义在：nvAR_defs.h

2.1.9. NvAR_Quaternion

以下是有关 NvAR_Quaternion 结构的详细信息。

            

            
struct NvAR_Quaternion {
  float x, y, z, w;
};
        

成员

x

类型：float

四元数复数部分的第一系数。

y

类型：float

四元数复数部分的第二系数。

z

类型：float

四元数复数部分的第三系数。

w

类型：float

四元数的标量系数。

备注

此结构体表示四元数中的系数，这些系数在以下方程中表示

定义在：nvAR_defs.h

2.1.10. NvAR_Rect

以下是关于 NvAR_Rect 结构的详细信息。

            

            
typedef struct NvAR_Rect {
  float x, y, width, height;
} NvAR_Rect;
        

成员

x

类型：float

边界框左上角的 X 坐标，以像素为单位。

y

类型：float

边界框左上角的 Y 坐标，以像素为单位。

width

类型：float

边界框的宽度，以像素为单位。

height

类型：float

边界框的高度，以像素为单位。

备注

此结构体表示矩形 2D 边界框的位置和大小。

定义在：nvAR_defs.h

2.1.11. NvAR_RenderingParams

以下是关于 NvAR_RenderingParams 结构的详细信息。

            

            
struct NvAR_RenderingParams {
  NvAR_Frustum frustum;
  NvAR_Quaternion rotation;
  NvAR_Vec3<float> translation;
};
        

成员

frustum

类型: NvAR_Frustum

正交相机的相机视锥体。

rotation

类型: NvAR_Quaternion

相机相对于网格的旋转。

translation

类型: NvAR_Vec3<float>

相机相对于网格的平移。

备注

此结构体定义了用于在计算机屏幕的窗口中绘制 3D 人脸网格的参数，以便人脸网格与相应的视频帧对齐。 投影矩阵由 frustum 参数构建，模型视图矩阵由 rotation 和 translation 参数构建。

定义在：nvAR_defs.h

2.1.12. NvAR_Vector2f

以下是关于 NvAR_Vector2f 结构的详细信息。

            

            
typedef struct NvAR_Vector2f {
  float x, y;
} NvAR_Vector2f;
        

成员

x

类型：float

2D 向量的 X 分量。

y

类型：float

2D 向量的 Y 分量。

备注

此结构体表示一个 2D 向量。

定义在：nvAR_defs.h

2.1.13. NvAR_Vector3f

以下是关于 NvAR_Vector3f 结构的详细信息。

            

            
typedef struct NvAR_Vector3f {
  float vec[3];
} NvAR_Vector3f;
        

成员

vec

类型: 大小为 3 的 float 数组

大小为 3 的向量。

备注

此结构体表示一个 3D 向量。

定义在：nvAR_defs.h

2.1.14. NvAR_Vector3u16

以下是关于 NvAR_Vector3u16 结构的详细信息。

            

            
typedef struct NvAR_Vector3u16 {
unsigned short vec[3];
} NvAR_Vector3u16;
        

成员

vec

类型: 大小为 3 的 unsigned short 数组

大小为 3 的向量。

备注

此结构体表示一个 3D 向量。

定义在：nvAR_defs.h

2.2. Functions

本节提供有关 AR SDK 中函数的信息。

2.2.1. NvAR_Create

以下是关于 NvAR_Create 结构的详细信息。

            

            
NvAR_Result NvAR_Create(
  NvAR_FeatureID featureID,
  NvAR_FeatureHandle *handle
);
        

参数

featureID [in]

类型: NvAR_FeatureID

要创建的功能的类型。

handle[out]

类型: NvAR_FeatureHandle *

指向新创建的功能实例的句柄。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_FEATURENOTFOUND
• NVCV_ERR_INITIALIZATION

备注

此函数创建指定功能类型的实例，并将指向该功能实例的句柄写入 handle out 参数。

2.2.2. NvAR_Destroy

以下是关于 NvAR_Destroy 结构的详细信息。

            

            
NvAR_Result NvAR_Destroy(
  NvAR_FeatureHandle handle
);
        

参数

handle [in]

类型: NvAR_FeatureHandle

要释放的功能实例的句柄。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_FEATURENOTFOUND

备注

此函数释放具有指定句柄的功能实例。 由于句柄不是引用计数的，因此在此函数调用后，句柄将无效。

2.2.3. NvAR_Load

以下是关于 NvAR_Load 结构的详细信息。

            

            
NvAR_Result NvAR_Load(
  NvAR_FeatureHandle handle,
);
        

参数

handle [in]

类型: NvAR_FeatureHandle

要加载的功能实例的句柄。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_MISSINGINPUT
• NVCV_ERR_FEATURENOTFOUND
• NVCV_ERR_INITIALIZATION
• NVCV_ERR_UNIMPLEMENTED

备注

此函数加载指定的功能实例，并验证为该功能实例设置的任何配置属性。

2.2.4. NvAR_Run

以下是关于 NvAR_Run 结构的详细信息。

            

            
NvAR_Result NvAR_Run(
  NvAR_FeatureHandle handle,
);
        

参数

handle[in]

类型: const NvAR_FeatureHandle

要运行的功能实例的句柄。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_GENERAL
• NVCV_ERR_FEATURENOTFOUND
• NVCV_ERR_MEMORY
• NVCV_ERR_MISSINGINPUT
• NVCV_ERR_PARAMETER

备注

此函数验证用户设置的输入/输出属性，使用为实例设置的输入属性运行指定的功能实例，并将结果写入为实例设置的输出属性。 输入和输出属性由访问器函数设置。 有关更多信息，请参阅NVIDIA AR SDK 访问器函数摘要。

2.2.5. NvAR_GetCudaStream

以下是关于 NvAR_GetCudaStream 结构的详细信息。

            

            
NvAR_GetCudaStream(
   NvAR_FeatureHandle handle,
   const char *name,
   const CUStream *stream
);
        

参数

handle

类型: NvAR_FeatureHandle

要从中获取 CUDA 流的功能实例的句柄。

name

类型: const char *

NvAR_Parameter_Config(CUDAStream) 键值。 任何其他键值都将返回错误。

stream

类型: const CUStream *

指向要写入检索到的 CUDA 流的 CUDA 流的指针。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_MISSINGINPUT
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数获取指定功能实例将在其中运行的 CUDA 流，并将要检索的 CUDA 流写入由 stream 参数指定的位置。

2.2.6. NvAR_CudaStreamCreate

以下是关于 NvAR_CudaStreamCreate 结构的详细信息。

            

            
NvCV_Status NvAR_CudaStreamCreate(
  CUstream *stream
);
        

参数

stream [out]

类型: CUstream *

用于存储新分配的 CUDA 流的位置。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_CUDA_VALUE 如果 CUDA 参数不在其可接受的范围内。

备注

此函数创建一个 CUDA 流。 它是 CUDA 运行时 API 函数 cudaStreamCreate() 的包装器，您可以使用它来避免与 NVIDIA CUDA Toolkit 库链接。 此函数和 cudaStreamCreate() 是等效且可互换的。

2.2.7. NvAR_CudaStreamDestroy

以下是关于 NvAR_CudaStreamDestroy 结构的详细信息。

            

            
void NvAR_CudaStreamDestroy(
  CUstream stream
);
        

参数

stream [in]

类型: CUstream

要销毁的 CUDA 流。

返回值

不返回值。

备注

此函数销毁 CUDA 流。 它是 CUDA 运行时 API 函数 cudaStreamDestroy() 的包装器，您可以使用它来避免与 NVIDIA CUDA Toolkit 库链接。 此函数和 cudaStreamDestroy() 是等效且可互换的。

2.2.8. NvAR_GetF32

以下是关于 NvAR_GetF32 结构的详细信息。

            

            
NvAR_GetF32(
   NvAR_FeatureHandle handle,
   const char *name,
   float *val
);
        

参数

handle

类型: NvAR_FeatureHandle

要从中获取指定的 32 位浮点参数的功能实例的句柄。

name

类型: const char *

用于访问 32 位浮点参数的键值，如 nvAR_defs.h 和 功能类型属性中的键值 中所定义。

val

类型: float*

指向要写入检索到的值的 32 位浮点数的指针。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数获取指定功能实例的指定单精度（32 位）浮点参数的值，并将要检索的值写入由 val 参数指定的位置。

2.2.9. NvAR_GetF64

以下是关于 NvAR_GetF64 结构的详细信息。

            

            
NvAR_GetF64(
   NvAR_FeatureHandle handle,
   const char *name,
   double *val
);
        

参数

handle

类型: NvAR_FeatureHandle

要从中获取指定的 64 位浮点参数的功能实例的句柄。

name

类型: const char *

用于访问 64 位双精度参数的键值，如 nvAR_defs.h 和 功能类型属性中的键值 中所定义。

val

类型: double*

指向要写入检索到的值的 64 位双精度浮点数的指针。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数获取指定功能实例的指定双精度（64 位）浮点参数的值，并将检索到的值写入由 val 参数指定的位置。

2.2.10. NvAR_GetF32Array

以下是关于 NvAR_GetF32Array 结构的详细信息。

            

            
NvAR_GetFloatArray (
   NvAR_FeatureHandle handle,
   const char *name,
   const float** vals,
   int *count
);
        

参数

handle

类型: NvAR_FeatureHandle

要从中获取指定的 float 数组的功能实例的句柄。

name

类型: const char *

有关键值的完整列表，请参阅功能类型属性中的键值。

vals

类型: const float**

指向浮点数数组的指针，检索到的值将写入该数组。

count

类型: int *

当前未使用。 由 vals 参数指定的数组中的元素数。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_MISSINGINPUT
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数获取指定功能实例的指定浮点数组中的值，并将检索到的值写入由 vals 参数指定的位置的数组中。

2.2.11. NvAR_GetObject

以下是关于 NvAR_GetObject 结构的详细信息。

            

            
NvAR_GetObject(
   NvAR_FeatureHandle handle,
   const char *name,
   const void **ptr,
   unsigned long typeSize
);
        

参数

handle

类型: NvAR_FeatureHandle

要从中获取指定对象的功能实例的句柄。

name

类型: const char *

有关键值的完整列表，请参阅功能类型属性中的键值。

ptr

类型: const void**

指向为 结构体 中定义的对象分配的内存的指针。

typeSize

类型: unsigned long

指针指向的项的大小。 如果大小不匹配，则返回 NVCV_ERR_MISMATCH。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_MISSINGINPUT
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数获取指定功能实例的指定对象，并将该对象存储在由 ptr 参数指定的内存位置中。

2.2.12. NvAR_GetS32

以下是关于 NvAR_GetS32 结构的详细信息。

            

            
NvAR_GetS32(
   NvAR_FeatureHandle handle,
   const char *name,
   int *val
);
        

参数

handle

类型: NvAR_FeatureHandle

要从中获取指定的 32 位有符号整数参数的功能实例的句柄。

name

类型: const char *

用于访问有符号整数参数的键值，如 nvAR_defs.h 和 功能类型属性中的键值 中所定义。

val

类型: int*

指向要写入检索到的值的 32 位有符号整数的指针。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数获取指定功能实例的指定 32 位有符号整数参数的值，并将检索到的值写入由 val 参数指定的位置。

2.2.13. NvAR_GetString

以下是关于 NvAR_GetString 结构的详细信息。

            

            
NvAR_GetString(
   NvAR_FeatureHandle handle,
   const char *name,
   const char** str
);
        

参数

handle

类型: NvAR_FeatureHandle

要从中获取指定的字符串参数的功能实例的句柄。

name

类型: const char *

有关键值的完整列表，请参阅功能类型属性中的键值。

str

类型: const char**

请求的字符串指针存储在其中的地址。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_MISSINGINPUT
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数获取指定功能实例的指定字符串参数的值，并将检索到的字符串写入由 str 参数指定的位置。

2.2.14. NvAR_GetU32

以下是关于 NvAR_GetU32 结构的详细信息。

            

            
NvAR_GetU32(
   NvAR_FeatureHandle handle,
   const char *name,
   unsigned int* val
);
        

参数

handle

类型: NvAR_FeatureHandle

要从中获取指定的 32 位无符号整数参数的功能实例的句柄。

name

类型: const char *

用于访问无符号整数参数的键值，如 nvAR_defs.h 和 功能类型属性中的键值 中所定义。

val

类型: unsigned int*

指向要写入检索到的值的 32 位无符号整数的指针。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数获取指定功能实例的指定 32 位无符号整数参数的值，并将检索到的值写入由 val 参数指定的位置。

2.2.15. NvAR_GetU64

以下是关于 NvAR_GetU64 结构的详细信息。

            

            
NvAR_GetU64(
   NvAR_FeatureHandle handle,
   const char *name,
   unsigned long long *val
);
        

参数

handle

类型: NvAR_FeatureHandle

要从中获取指定的 64 位无符号整数参数的已返回功能实例的句柄。

name

类型: const char *

用于访问无符号 64 位整数参数的键值，如 nvAR_defs.h 和 功能类型属性中的键值 中所定义。

val

类型: unsigned long long*

指向要写入检索到的值的 64 位无符号整数的指针。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数获取指定功能实例的指定 64 位无符号整数参数的值，并将检索到的值写入由 va1 参数指定的位置。

2.2.16. NvAR_SetCudaStream

以下是关于 NvAR_SetCudaStream 结构的详细信息。

            

            
NvAR_SetCudaStream(
   NvAR_FeatureHandle handle,
   const char *name,
   CUStream stream
);
        

参数

handle

类型: NvAR_FeatureHandle

要为其设置 CUDA 流的已返回功能实例的句柄。

name

类型: const char *

NvAR_Parameter_Config(CUDAStream) 键值。 任何其他键值都将返回错误。

stream

类型: CUStream

要在 GPU 上运行功能实例的 CUDA 流。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数将指定功能实例将在其中运行的 CUDA 流设置为参数流。

定义于: nvAR.h

2.2.17. NvAR_SetF32

以下是关于 NvAR_SetF32 结构的详细信息。

            

            
NvAR_SetF32(
   NvAR_FeatureHandle handle,
   const char *name,
   float val
);
        

参数

handle

类型: NvAR_FeatureHandle

要为其设置指定的 32 位浮点参数的功能实例的句柄。

name

类型: const char *

用于访问 32 位浮点参数的键值，如 nvAR_defs.h 和 功能类型属性中的键值 中所定义。

val

类型：float

参数要设置为的 32 位浮点数。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数将指定功能实例的指定单精度（32 位）浮点参数设置为 val 参数。

2.2.18. NvAR_SetF64

以下是关于 NvAR_SetF64 结构的详细信息。

            

            
NvAR_SetF64(
   NvAR_FeatureHandle handle,
   const char *name,
   double val
);
        

参数

handle

类型: NvAR_FeatureHandle

要为其设置指定的 64 位浮点参数的功能实例的句柄。

name

类型: const char *

用于访问 64 位浮点参数的键值，如 nvAR_defs.h 和 功能类型属性中的键值 中所定义。

val

类型: double

参数将设置为的 64 位双精度浮点数。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数将指定功能实例的指定双精度（64 位）浮点参数设置为 val 参数。

2.2.19. NvAR_SetF32Array

以下是关于 NvAR_SetF32Array 结构的详细信息。

            

            
NvAR_SetFloatArray(
   NvAR_FeatureHandle handle,
   const char *name,
   float* vals,
   int count
);
        

参数

handle

类型: NvAR_FeatureHandle

要为其设置指定的 float 数组的功能实例的句柄。

name

类型: const char *

有关键值的完整列表，请参阅功能类型属性中的键值。

vals

类型: float*

参数将设置为的浮点数数组。

count

类型: int

当前未使用。 由 vals 参数指定的数组中的元素数。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数将由 vals 参数定义的浮点数数组分配给指定功能实例的指定浮点数组参数。

2.2.20. NvAR_SetObject

以下是关于 NvAR_SetObject 结构的详细信息。

            

            
NvAR_SetObject(
   NvAR_FeatureHandle handle,
   const char *name,
   void *ptr,
   unsigned long typeSize
);
        

参数

handle

类型: NvAR_FeatureHandle

要为其设置指定对象的功能实例的句柄。

name

类型: const char *

有关键值的完整列表，请参阅功能类型属性中的键值。

ptr

类型: void*

指向为 结构体 中定义的对象分配的内存的指针。

typeSize

类型: unsigned long

指针指向的项的大小。 如果大小不匹配，则返回 NVCV_ERR_MISMATCH。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数将由 ptr 参数指定的对象的内存分配给指定功能实例的指定对象参数。

2.2.21. NvAR_SetS32

以下是关于 NvAR_SetS32 结构的详细信息。

            

            
NvAR_SetS32(
   NvAR_FeatureHandle handle,
   const char *name,
   int val
);
        

参数

handle

类型: NvAR_FeatureHandle

要为其设置指定的 32 位有符号整数参数的功能实例的句柄。

name

类型: const char *

用于访问有符号 32 位整数参数的键值，如 nvAR_defs.h 和 功能类型属性中的键值 中所定义。

val

类型: int

参数将设置为的 32 位有符号整数。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数将指定功能实例的指定 32 位有符号整数参数设置为 val 参数。

2.2.22. NvAR_SetString

以下是关于 NvAR_SetString 结构的详细信息。

            

            
NvAR_SetString(
   NvAR_FeatureHandle handle,
   const char *name,
   const char* str
);
        

参数

handle

类型: NvAR_FeatureHandle

要为其设置指定的字符串参数的功能实例的句柄。

name

类型: const char *

有关键值的完整列表，请参阅功能类型属性中的键值。

str

类型: const char*

指向要将参数设置为的字符串的指针。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数将指定功能实例的指定字符串参数的值设置为 str 参数。

2.2.23. NvAR_SetU32

以下是关于 NvAR_SetU32 结构的详细信息。

            

            
NvAR_SetU32(
   NvAR_FeatureHandle handle,
   const char *name,
   unsigned int val
);
        

参数

handle

类型: NvAR_FeatureHandle

要为其设置指定的 32 位无符号整数参数的功能实例的句柄。

name

类型: const char *

用于访问无符号 32 位整数参数的键值，如 nvAR_defs.h 和 NVIDIA AR SDK 访问器函数摘要 中所定义。

val

类型: unsigned int

要将参数设置为的 32 位无符号整数。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数将指定功能实例的指定 32 位无符号整数参数的值设置为 val 参数。

2.2.24. NvAR_SetU64

以下是关于 NvAR_SetU64 结构的详细信息。

            

            
NvAR_SetU64(
   NvAR_FeatureHandle handle,
   const char *name,
   unsigned long long val
);
        

参数

handle

类型: NvAR_FeatureHandle

要为其设置指定的 64 位无符号整数参数的功能实例的句柄。

name

类型: const char *

用于访问无符号 64 位整数参数的键值，如 nvAR_defs.h 和 功能类型属性中的键值 中所定义。

val

类型: unsigned long long

要将参数设置为的 64 位无符号整数。

返回值

返回以下值之一：

• NVCV_SUCCESS 成功时返回
• NVCV_ERR_PARAMETER
• NVCV_ERR_SELECTOR
• NVCV_ERR_GENERAL
• NVCV_ERR_MISMATCH

备注

此函数将指定功能实例的指定 64 位无符号整数参数的值设置为 val 参数。

2.3. Return Codes

NvCV_Status 枚举定义了 AR SDK 函数可能返回的以下值，以指示错误或成功。

NVCV_SUCCESS = 0

成功执行。

NVCV_ERR_GENERAL

通用错误代码，指示函数由于未指定的原因而执行失败。

NVCV_ERR_UNIMPLEMENTED

请求的功能未实现。

NVCV_ERR_MEMORY

请求的操作需要的内存超过可用内存。

NVCV_ERR_EFFECT

已提供无效的效果句柄。

NVCV_ERR_SELECTOR

指定的选择器对此效果滤镜无效。

NVCV_ERR_BUFFER

未指定任何图像缓冲区。

NVCV_ERR_PARAMETER

已为此效果和选择器字符串的组合提供无效的参数值。

NVCV_ERR_MISMATCH

某些参数（例如，图像格式或图像尺寸）未正确匹配。

NVCV_ERR_PIXELFORMAT

不支持指定的像素格式。

NVCV_ERR_MODEL

加载 TRT 模型时发生错误。

NVCV_ERR_LIBRARY

加载动态库时出错。

NVCV_ERR_INITIALIZATION

效果未正确初始化。

NVCV_ERR_FILE

找不到指定的文件。

NVCV_ERR_FEATURENOTFOUND

找不到请求的功能。

NVCV_ERR_MISSINGINPUT

未设置必需的参数。

NVCV_ERR_RESOLUTION

不支持指定的图像分辨率。

NVCV_ERR_UNSUPPORTEDGPU

不支持此 GPU。

NVCV_ERR_WRONGGPU

当前 GPU 不是所选的 GPU。

NVCV_ERR_UNSUPPORTEDDRIVER

当前安装的图形驱动程序不受支持。

NVCV_ERR_MODELDEPENDENCIES

没有与此系统匹配的具有依赖关系的模型。

NVCV_ERR_PARSE

读取文件时出现解析或语法错误。

NVCV_ERR_MODELSUBSTITUTION

指定的模型不存在，并且已被替换。

NVCV_ERR_READ

读取文件时发生错误。

NVCV_ERR_WRITE

写入文件时发生错误。

NVCV_ERR_PARAMREADONLY

所选参数为只读。

NVCV_ERR_TRT_ENQUEUE

TensorRT 入队失败。

NVCV_ERR_TRT_BINDINGS

意外的 TensorRT 绑定。

NVCV_ERR_TRT_CONTEXT

创建 TensorRT 上下文时发生错误。

NVCV_ERR_TRT_INFER

创建推理引擎时出现问题。

NVCV_ERR_TRT_ENGINE

反序列化推理运行时引擎时出现问题。

NVCV_ERR_NPP

NPP 库中发生错误。

NVCV_ERR_CONFIG

没有适用于指定参数配置的合适模型。

NVCV_ERR_TOOSMALL

提供的参数或缓冲区不够大。

NVCV_ERR_TOOBIG

提供的参数太大。

NVCV_ERR_WRONGSIZE

提供的参数不是预期的大小。

NVCV_ERR_OBJECTNOTFOUND

找不到指定的对象。

NVCV_ERR_SINGULAR

遇到数学奇点。

NVCV_ERR_NOTHINGRENDERED

在指定区域中未渲染任何内容。

NVCV_ERR_OPENGL

发生 OpenGL 错误。

NVCV_ERR_DIRECT3D

发生 Direct3D 错误。

NVCV_ERR_CUDA_MEMORY

请求的操作需要的 CUDA 内存超过可用内存。

NVCV_ERR_CUDA_VALUE

CUDA 参数不在其可接受的范围内。

NVCV_ERR_CUDA_PITCH

CUDA pitch 不在其可接受的范围内。

NVCV_ERR_CUDA_INIT

CUDA 驱动程序和运行时无法初始化。

NVCV_ERR_CUDA_LAUNCH

CUDA 内核启动失败。

NVCV_ERR_CUDA_KERNEL

没有适用于设备的合适内核映像。

NVCV_ERR_CUDA_DRIVER

安装的 NVIDIA CUDA 驱动程序早于 CUDA 运行时库。

NVCV_ERR_CUDA_UNSUPPORTED

当前系统或设备不支持 CUDA 操作。

NVCV_ERR_CUDA_ILLEGAL_ADDRESS

CUDA 尝试加载或存储无效的内存地址。

NVCV_ERR_CUDA

发生未指定的 CUDA 错误。

还有许多其他与 CUDA 相关的错误未在此处列出。但是，函数 NvCV_GetErrorStringFromCode() 会将错误代码转换为字符串，以帮助您进行调试。

NVIDIA 3DMM 文件格式基于封装的对象，这些对象由 FOURCC 标签和 32 位大小限定范围。标头必须首先出现在文件中。对象及其子对象可以以任何顺序出现。在本指南中，它们按默认顺序列出。

A.1. 标头

标头包含以下信息

• 名称 NFAC。
• size=8
• endian=0xe4 (小端)
• sizeBits=32
• indexBits=16
• 目录表的偏移量。

A.2. 模型对象

模型对象包含形状组件和可选的颜色组件。

两个对象都包含以下信息：

• 平均形状。
• 一组形状模式。
• 模式的特征值。
• 三角形列表。

A.3. IBUG 映射对象

以下是关于 IBUG 映射对象的一些信息。

IBUG 映射对象包含以下信息：

• Landmarks
• 右轮廓
• 左轮廓

A.4. 混合形状对象

混合形状对象包含一组混合形状，每个混合形状都有一个名称。

A.5. 模型轮廓对象

模型轮廓对象包含右轮廓和左轮廓。

A.6. 拓扑对象

拓扑包含相邻面和顶点的对列表。

A.7. NVIDIA 地标对象

NVIDIA 将地标的数量从 68 个扩展到 126 个，包括左右两侧更详细的轮廓。

A.8. 分区对象

这会将网格划分为相同材质的连贯子网格，用于渲染。

A.9. 目录表对象

可选的目录表对象包含标记对象及其偏移量的列表。此对象可用于随机访问对象。文件通常按顺序读取。

3D 身体姿势由 34 个用于身体姿势跟踪的关键点组成。

B.1. 身体姿势跟踪的 34 个关键点

以下是 34 个关键点的列表。

身体姿势跟踪的 34 个关键点是：骨盆、左髋、右髋、躯干、左膝、右膝、颈部、左踝、右踝、左脚大脚趾、右脚大脚趾、左小脚趾、右小脚趾、左脚跟、右脚跟、鼻子、左眼、右眼、左耳、右耳、左肩、右肩、左肘、右肘、左手腕、右手腕、左小指指节、右小指指节、左中指指尖、右中指指尖、左食指指节、右食指指节、左拇指指尖、右拇指指尖。

以下是骨骼结构的列表

B.2. NvAR_Parameter_Output(KeyPoints) 顺序

以下是关于关键点顺序的一些信息。

来自 NvAR_Parameter_Output(KeyPoints) 的输出的关键点顺序与身体姿势跟踪的 34 个关键点中提到的相同。

SDK 附带了人脸拟合功能使用的默认人脸模型。此模型是 ICT 人脸模型 https://github.com/ICT-VGL/ICT-FaceKit 的修改版本。人脸模型的修改版本针对实时人脸拟合应用进行了优化，因此分辨率较低。此模型是版本 face_model2.nvf。除了 ICT 模型提供的混合形状外，它还使用用于眼睛注视表情的线性混合形状，这使其可以用于隐式注视跟踪。

在下图中，左侧是原始 ICT 人脸模型拓扑，右侧是修改后的 face_model2.nvf 人脸模型拓扑。

C.1. 面部表情列表

以下是面部表情估计功能中使用的所有表情混合形状的图形可视化。

以下是人脸 3D 网格功能和面部表情估计功能中使用的面部混合形状表情列表：

• 0: BrowDown_L
• 1: BrowDown_R
• 2: BrowInnerUp_L
• 3: BrowInnerUp_R
• 4: BrowOuterUp_L
• 5: BrowOuterUp_R
• 6: cheekPuff_L
• 7: cheekPuff_R
• 8: cheekSquint_L
• 9: cheekSquint_R
• 10: eyeBlink_L
• 11: eyeBlink_R
• 12: eyeLookDown_L
• 13: eyeLookDown_R
• 14: eyeLookIn_L
• 15: eyeLookIn_R
• 16: eyeLookOut_L
• 17: eyeLookOut_R
• 18: eyeLookUp_L
• 19: eyeLookUp_R
• 20: eyeSquint_L
• 21: eyeSquint_R
• 22: eyeWide_L
• 23: eyeWide_R
• 24: jawForward
• 25: jawLeft
• 26: jawOpen
• 27: jawRight
• 28: mouthClose
• 29: mouthDimple_L
• 30: mouthDimple_R
• 31: mouthFrown_L
• 32: mouthFrown_R
• 33: mouthFunnel
• 34: mouthLeft
• 35: mouthLowerDown_L
• 36: mouthLowerDown_R
• 37: mouthPress_L
• 38: mouthPress_R
• 39: mouthPucker
• 40: mouthRight
• 41: mouthRollLower
• 42: mouthRollUpper
• 43: mouthShrugLower
• 44: mouthShrugUpper
• 45: mouthSmile_L
• 46: mouthSmile_R
• 47: mouthStretch_L
• 48: mouthStretch_R
• 49: mouthUpperUp_L
• 50: mouthUpperUp_R
• 51: noseSneer_L
• 52: noseSneer_R

可以使用以下选项将上面列表中的项目映射到 ARKit 混合形状：

• A01_Brow_Inner_Up = 0.5 * (browInnerUp_L + browInnerUp_R)
• A02_Brow_Down_Left = browDown_L
• A03_Brow_Down_Right = browDown_R
• A04_Brow_Outer_Up_Left = browOuterUp_L
• A05_Brow_Outer_Up_Right = browOuterUp_R
• A06_Eye_Look_Up_Left = eyeLookUp_L
• A07_Eye_Look_Up_Right = eyeLookUp_R
• A08_Eye_Look_Down_Left = eyeLookDown_L
• A09_Eye_Look_Down_Right = eyeLookDown_R
• A10_Eye_Look_Out_Left = eyeLookOut_L
• A11_Eye_Look_In_Left = eyeLookIn_L
• A12_Eye_Look_In_Right = eyeLookIn_R
• A13_Eye_Look_Out_Right = eyeLookOut_R
• A14_Eye_Blink_Left = eyeBlink_L
• A15_Eye_Blink_Right = eyeBlink_R
• A16_Eye_Squint_Left = eyeSquint_L
• A17_Eye_Squint_Right = eyeSquint_R
• A18_Eye_Wide_Left = eyeWide_L
• A19_Eye_Wide_Right = eyeWide_R
• A20_Cheek_Puff = 0.5 * (cheekPuff_L + cheekPuff_R)
• A21_Cheek_Squint_Left = cheekSquint_L
• A22_Cheek_Squint_Right = cheekSquint_R
• A23_Nose_Sneer_Left = noseSneer_L
• A24_Nose_Sneer_Right = noseSneer_R
• A25_Jaw_Open = jawOpen
• A26_Jaw_Forward = jawForward
• A27_Jaw_Left = jawLeft
• A28_Jaw_Right = jawRight
• A29_Mouth_Funnel = mouthFunnel
• A30_Mouth_Pucker = mouthPucker
• A31_Mouth_Left = mouthLeft
• A32_Mouth_Right = mouthRight
• A33_Mouth_Roll_Upper = mouthRollUpper
• A34_Mouth_Roll_Lower = mouthRollLower
• A35_Mouth_Shrug_Upper = mouthShrugUpper
• A36_Mouth_Shrug_Lower = mouthShrugLower
• A37_Mouth_Close = mouthClose
• A38_Mouth_Smile_Left = mouthSmile_L
• A39_Mouth_Smile_Right = mouthSmile_R
• A40_Mouth_Frown_Left = mouthFrown_L
• A41_Mouth_Frown_Right = mouthFrown_R
• A42_Mouth_Dimple_Left = mouthDimple_L
• A43_Mouth_Dimple_Right = mouthDimple_R
• A44_Mouth_Upper_Up_Left = mouthUpperUp_L
• A45_Mouth_Upper_Up_Right = mouthUpperUp_R
• A46_Mouth_Lower_Down_Left = mouthLowerDown_L
• A47_Mouth_Lower_Down_Right = mouthLowerDown_R
• A48_Mouth_Press_Left = mouthPress_L
• A49_Mouth_Press_Right = mouthPress_R
• A50_Mouth_Stretch_Left = mouthStretch_L
• A51_Mouth_Stretch_Right = mouthStretch_R
• A52_Tongue_Out = 0

本文档可能引用定义虚拟 3D 对象的不同坐标系。本附录定义了可以通过 SDK 交互的不同坐标空间。

D.1. NvAR 世界 3D 空间

以下是人脸 3D 网格功能和面部表情估计功能中使用的面部混合形状表情列表

NvAR 世界 3D 空间，或简称为 世界空间，定义了 3D 应用中使用的主要参考系。参考系是右手坐标系，坐标单位为厘米。相机通常（但不总是）放置为沿负 z 轴向下看，x 轴指向右侧，y 轴指向上方。人脸模型通常（但不总是）放置为正 z 轴从模型的鼻子向外指出，x 轴从左耳向外指出，y 轴从头部指向上方。这样，人脸模型或相机模型的旋转都不会对应于模型在视野中。

图 1. NvAR 世界 3D 空间

D.2. NvAR 模型 3D 空间

在 NvAR 模型 3D 空间，或简称为 模型空间 中，人脸模型的原点位于颅骨中心，即第一个颈部关节的位置。参考系是右手坐标系，坐标单位为厘米。正 z 轴从模型的鼻子向外指出，x 轴从左耳向外指出，y 轴从头部指向上方。

图 2. NvAR 模型 3D 空间

D.3. NvAR 相机 3D 空间

在 NvAR 相机 3D 空间 或简称为 相机空间 中，对象相对于特定相机放置。在许多情况下，相机空间可以与世界空间相同，除非使用显式相机外参。参考系是右手坐标系，坐标单位为厘米。正 x 轴指向右侧，y 轴指向上方，z 轴指向后方。

图 3. NvAR 相机 3D 空间

D.4. NvAR 图像 2D 空间

NvAR 图像 2D 空间，或 屏幕空间 是屏幕坐标的主要 2D 空间。图像的原点是最上方、最左侧像素的位置；x 轴指向右侧，y 轴指向下方。此坐标系的单位是像素。

图 4. NvAR 图像 2D 空间

此坐标系有两种不同的风格，即像素上或像素间。

在像素上系统中，原点位于像素的中心。在像素间系统中，原点从像素中心偏移，沿 x 轴和 y 轴偏移 -0.5 像素的距离。像素上系统应用于基于整数的坐标，而像素间系统应用于实数值坐标（通常定义为浮点坐标）。

像素上整数坐标	像素间实数值坐标

声明

本文档仅供参考，不得视为对产品的特定功能、状况或质量的保证。NVIDIA Corporation（“NVIDIA”）对本文档中包含信息的准确性或完整性不作任何明示或暗示的陈述或保证，并且对本文档中包含的任何错误不承担任何责任。对于因使用此类信息而造成的后果或使用，或因其使用可能导致的侵犯第三方专利或其他权利的行为，NVIDIA 概不负责。本文档不构成对开发、发布或交付任何材料（如下定义）、代码或功能的承诺。

NVIDIA 保留随时修改、修正、增强、改进本文档以及进行任何其他更改的权利，恕不另行通知。

客户在下订单前应获取最新的相关信息，并应验证此类信息是否为最新且完整。

NVIDIA 产品的销售受订单确认时提供的 NVIDIA 标准销售条款和条件的约束，除非 NVIDIA 和客户的授权代表签署的个别销售协议（“销售条款”）另有约定。NVIDIA 特此明确反对将任何客户通用条款和条件应用于购买本文档中引用的 NVIDIA 产品。本文档不直接或间接地形成任何合同义务。

NVIDIA 产品并非设计、授权或保证适用于医疗、军事、航空、航天或生命支持设备，也不适用于 NVIDIA 产品的故障或失灵可能合理预期会导致人身伤害、死亡或财产或环境损害的应用。对于在上述设备或应用中包含和/或使用 NVIDIA 产品，NVIDIA 不承担任何责任，因此，此类包含和/或使用由客户自行承担风险。

NVIDIA 不保证或声明基于本文档的产品将适用于任何特定用途。NVIDIA 不一定会对每种产品的所有参数进行测试。客户有责任自行评估并确定本文档中包含的任何信息的适用性，确保产品适合并满足客户计划的应用，并为该应用执行必要的测试，以避免应用或产品的默认设置。客户产品设计中的缺陷可能会影响 NVIDIA 产品的质量和可靠性，并可能导致超出本文档中包含的附加或不同条件和/或要求。对于可能基于或归因于以下原因的任何默认设置、损坏、成本或问题，NVIDIA 概不负责：(i) 以任何违反本文档的方式使用 NVIDIA 产品，或 (ii) 客户产品设计。

本文档未授予 NVIDIA 专利权、版权或其他 NVIDIA 知识产权下的任何明示或暗示的许可。NVIDIA 发布的关于第三方产品或服务的信息不构成 NVIDIA 授予使用此类产品或服务的许可，也不构成对其的保证或认可。使用此类信息可能需要获得第三方专利或其他知识产权下的第三方许可，或获得 NVIDIA 专利或其他 NVIDIA 知识产权下的 NVIDIA 许可。

仅在事先获得 NVIDIA 书面批准的情况下，才允许复制本文档中的信息，复制时不得进行修改，并且必须完全遵守所有适用的出口法律和法规，并附带所有相关的条件、限制和声明。

本文档和所有 NVIDIA 设计规范、参考板、文件、图纸、诊断程序、列表和其他文档（统称为“材料”，单独称为“材料”）均“按原样”提供。NVIDIA 对材料不作任何明示、暗示、法定或其他形式的保证，并明确声明不承担任何关于不侵权、适销性和适用于特定用途的暗示保证。在法律未禁止的范围内，在任何情况下，NVIDIA 均不对因使用本文档而引起的任何损害负责，包括但不限于任何直接、间接、特殊、附带、惩罚性或后果性损害，无论其发生原因和责任理论如何，即使 NVIDIA 已被告知可能发生此类损害。尽管客户可能因任何原因而遭受任何损害，但 NVIDIA 对本文所述产品的客户承担的累计总责任应根据产品的销售条款进行限制。

VESA DisplayPort

DisplayPort 和 DisplayPort Compliance Logo、DisplayPort Compliance Logo for Dual-mode Sources 以及 DisplayPort Compliance Logo for Active Cables 是视频电子标准协会在美国和其他国家/地区拥有的商标。

HDMI

HDMI、HDMI 标志和 High-Definition Multimedia Interface 是 HDMI Licensing LLC 的商标或注册商标。

OpenCL

OpenCL 是 Apple Inc. 的商标，已获得 Khronos Group Inc. 的许可使用。

商标

NVIDIA、NVIDIA 徽标以及 cuBLAS、CUDA、CUDA Toolkit、cuDNN、DALI、DIGITS、DGX、DGX-1、DGX-2、DGX Station、DLProf、GPU、JetPack、Jetson、Kepler、Maxwell、NCCL、Nsight Compute、Nsight Systems、NVCaffe、NVIDIA Ampere GPU 架构、NVIDIA Deep Learning SDK、NVIDIA Developer Program、NVIDIA GPU Cloud、NVLink、NVSHMEM、PerfWorks、Pascal、SDK Manager、T4、Tegra、TensorRT、TensorRT Inference Server、Tesla、TF-TRT、Triton Inference Server、Turing 和 Volta 是 NVIDIA Corporation 在美国和其他国家/地区的商标和/或注册商标。其他公司和产品名称可能是与其关联的各自公司的商标。