NVIDIA 现实增强AR开发工具包开发手册----Maxine AR SDK开发手册中文版

NVIDIA_Maxine_AR_SDK_API

点击此处加入NVIDIA开发者计划

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

1.1. Using the NVIDIA AR SDK in Applications

使用 NVIDIA AR SDK 使应用程序能够使用 SDK 的面部跟踪、面部特征点跟踪、3D 面部网格跟踪和 3D 身体姿势跟踪功能。

1.2. Creating an Instance of a Feature Type

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

创建特征类型的实例提供了对加载特征类型实例时使用的配置参数, 以及运行特征类型实例时在运行时提供的输入和输出参数的访问。

1. 为NvAR_FeatureHandle结构分配内存。

    NvAR_FeatureHandle faceDetectHandle{};

2. 调用NvAR_Create()函数。

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

   • NvAR_FeatureID枚举的值，用于标识特征类型。
   • 指向您声明为NvAR_FeatureHandle结构分配内存的变量的指针。

3. 要创建人脸检测特征类型的实例，请运行以下示例：

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

    NvAR_Create(NvAR_Feature_FaceDetection, &faceDetectHandle)

1.3. Getting and Setting Properties for a Feature Type

要准备加载和运行特征类型的实例，您需要设置实例所需的属性。

以下是一些属性：

• 加载特征类型所需的配置属性。

• 运行特征类型的实例时要在运行时提供的输入和输出属性。

完整列表，请参阅特征类型属性中的关键值。

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

1.3.1. Setting Up the CUDA Stream

某些 SDK 功能需要运行在 CUDA 流中。有关详细信息，请参阅NVIDIA CUDA 工具包文档。

1. 通过调用以下函数之一初始化 CUDA 流：

   • CUDA 运行时 API 函数cudaStreamCreate()
   • NvAR_CudaStreamCreate()

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

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. Summary of NVIDIA AR SDK Accessor Functions

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

Table 1. AR SDK Accessor Functions

Property Type	Data Type	Set and Get Accessor Function
32-bit unsigned integer	unsigned int	NvAR_SetU32()
		NvAR_GetU32()
32-bit signed integer	int	NvAR_SetS32()
		NvAR_GetS32()
Single-precision (32-bit) floating-point number	float	NvAR_SetF32()
		NvAR_GetF32()
Double-precision (64-bit) floating point number	double	NvAR_SetF64()
		NvAR_GetF64()
64-bit unsigned integer	unsigned long long	NvAR_SetU64()
		NvAR_GetU64()
Floating-point array	float*	NvAR_SetFloatArray()
		NvAR_GetFloatArray()
Object	void*	NvAR_SetObject()
		NvAR_GetObject()
Character string	const char*	NvAR_SetString()
		NvAR_GetString()
CUDA stream	CUstream	NvAR_SetCudaStream()
		NvAR_GetCudaStream()

1.3.3. Key Values in the Properties of a Feature Type

特征类型的属性中的关键值标识可用于每种特征类型的属性。每个键都有一个等效的字符串，并由一个宏定义，该宏指示属性的类别并将名称作为宏的输入。
以下是指示属性类别的宏：

• NvAR_Parameter_Config表示配置属性。

  请参阅配置属性。

• NvAR_Parameter_Input表示输入属性。

  请参阅输入属性。

• NvAR_Parameter_Output表示输出属性。

  请参阅输出属性。

这些名称是固定关键字，列在nvAR_defs.h中。根据属性是输入、输出还是配置属性，关键字可能会与不同的宏一起使用。

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

1.3.3.1. Configuration Properties

以下是 AR SDK 中的配置属性：

NvAR_Parameter_Config(FeatureDescription)

特征类型的描述。

等效字符串： NvAR_Parameter_Config_FeatureDescription

属性类型：character string (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
属性类型：character string (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)

用于描述形状的特征值的数量。

等效字符串： NvAR_Parameter_Config_ShapeEigenValueCount

属性类型：unsigned integer

NvAR_Parameter_Config(ExpressionCount)

用于表示表达式的系数的数量。

等效字符串： NvAR_Parameter_Config_ExpressionCount

属性类型：unsigned integer

NvAR_Parameter_Config(FocalLength)

用于 3D Body Pose 的相机焦距。

等效字符串： NvAR_Parameter_Config_FocalLength

属性类型：float

NvAR_Parameter_Config(UseCudaGraph)

启用 CUDA 图形优化的标志。 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
属性类型：object (void*)

1.3.3.2. Input Properties

以下是 AR SDK 中的输入属性：

NvAR_Parameter_Input(Image)

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

等效字符串： NvAR_Parameter_Input_Image

属性类型：object (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

属性类型：object (void*)

NvAR_Parameter_Input(BoundingBoxes)

确定包含NvAR_BBoxes类型人脸的输入图像的感兴趣区域 (ROI) 的边界框。

等效字符串： NvAR_Parameter_InputBoundingBoxes

属性类型：object (void*)

1.3.3.3. Output Properties

以下是 AR SDK 中的输出属性：

NvAR_Parameter_Output(BoundingBoxes)

CPU 输出 NvAR_BBoxes 类型的边界框。

等效字符串： NvAR_Parameter_Output_BoundingBoxes
属性类型：object (void*)

NvAR_Parameter_Output(BoundingBoxesConfidence)

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

等效字符串： NvAR_Parameter_Output_BoundingBoxesConfidence

属性类型：floating point array

NvAR_Parameter_Output(Landmarks)

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

等效字符串： NvAR_Parameter_Output_Landmarks

属性类型：object (void*)

NvAR_Parameter_Output(LandmarksConfidence)

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

等效字符串： NvAR_Parameter_Output_LandmarksConfidence

属性类型：floating point array

NvAR_Parameter_Output(Pose)

NvAR_Quaternion类型的 CPU 数组将输出检测到的姿势保存为 XYZW 四元数。

等效字符串： NvAR_Parameter_Output_Pose

属性类型：object (void*)

NvAR_Parameter_Output(FaceMesh)

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

等效字符串： NvAR_Parameter_Output_FaceMesh

属性类型：object (void*)

NvAR_Parameter_Output(RenderingParams)

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

等效字符串： NvAR_Parameter_Output_RenderingParams

属性类型：object (void*)

NvAR_Parameter_Output(ShapeEigenValues)

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

等效字符串： NvAR_Parameter_Output_ShapeEigenValues

属性类型：const floating point array

NvAR_Parameter_Output(ExpressionCoefficients)

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

等效字符串： NvAR_Parameter_Output_ExpressionCoefficients

属性类型：const floating point array

NvAR_Parameter_Output(KeyPoints)

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

等效字符串： NvAR_Parameter_Output_KeyPoints

属性类型：object (void*)

NvAR_Parameter_Output(KeyPoints3D)

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

等效字符串： NvAR_Parameter_Output_KeyPoints3D

属性类型：object (void*)

NvAR_Parameter_Output(JointAngles)

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

等效字符串： NvAR_Parameter_Output_JointAngles

属性类型：object (void*)

NvAR_Parameter_Output(KeyPointsConfidence)

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

等效字符串： NvAR_Parameter_Output_KeyPointsConfidence

属性类型：floating point array

NvAR_Parameter_Output(KeyPoints)

NvAR_Point2f类型的 CPU 输出缓冲区，用于保存输出检测到的 3D 身体姿势的 2D 关键点。有关信息，请参阅3D 身体姿势关键点格式。 CPU 缓冲区中点的顺序遵循3D Body Pose Keypoint Format中提到的顺序。

等效字符串： NvAR_Parameter_Output_KeyPoints

属性类型：object (void*)

NvAR_Parameter_Output(KeyPoints3D)

NvAR_Point3f 类型的 CPU 输出缓冲区，用于保存输出检测到的 3D 身体姿势的 3D 关键点。有关信息，请参阅3D 身体姿势关键点格式。 CPU 缓冲区中点的顺序遵循3D Body Pose Keypoint Format中提到的顺序。

等效字符串： NvAR_Parameter_Output_KeyPoints3D

属性类型：object (void*)

NvAR_Parameter_Output(JointAngles)

NvAR_Quaternion类型的 CPU 输出缓冲区用于保存 3D 身体姿势的关节旋转输出。

等效字符串： NvAR_Parameter_Output_JointAngles
属性类型：object (void*)

NvAR_Parameter_Output(KeyPointsConfidence)

每个检测到的 3D 身体姿势关键点的置信度浮点数组。

等效字符串： NvAR_Parameter_Output_KeyPointsConfidence

属性类型：floating point array

1.3.4. Getting the Value of a Property of a Feature

要获取特征属性的值，请调用适用于属性数据类型的 get 访问器函数。

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

• 特征实例的特征句柄。
• 标识您正在获取的属性的键值。
• 您希望写入属性值的内存位置。

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

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

1.3.5. Setting a Property for a Feature

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

1. 为功能所需的所有输入和输出以及可能需要的任何其他属性分配内存。

2. 调用适合属性数据类型的 set 访问器函数。

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

   • 特征实例的特征句柄。

   • 标识您正在设置的属性的键值。

   • 指向要设置属性的值的指针。

     此示例将文件路径设置为包含输出 3D 人脸模型的文件：

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

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

注意：它设置了一个 8 位大块/交错 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. Loading a Feature Instance

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

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

此示例加载人脸检测特征类型的实例：

NvAR_Load(faceDetectHandle);

1.3.7. Running a Feature Instance

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

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

此示例显示如何运行人脸检测功能实例：

NvAR_Run(faceDetectHandle);

1.3.8. Destroying a Feature Instance

当不再需要某个功能实例时，您需要将其销毁以释放该功能实例内部分配的资源和内存。

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

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

1.4. Working with Image Frames on GPU or CPU Buffers

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

有关 NvCVImage 的更多信息，请参阅NvCVImage API 指南。本节简要介绍了 AR SDK 中最常用的功能。

1.4.1. Converting Image Representations to NvCVImage Objects

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

注意： AR SDK 只为 RGB 图像提供包装函数。没有为 YUV 图像提供包装函数。

• 要为 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. Converting Other Image Representations to NvCVImage Objects

要转换其他图像表示，请调用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. Converting Decoded Frames from the NvDecoder to NvCVImage Objects

要将 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);

注意：上面的示例假定了高清内容的典型色彩空间规范。 SD 通常使用NVCV_601 。有 8 种可能的组合，您应该使用与视频标题中描述的视频相匹配的组合，或者通过反复试验继续进行。

以下是一些附加信息：

• 如果颜色不正确，请交换 709<->601。
• 如果它们被冲掉，请交换 VIDEO<->FULL。
• 如果颜色水平移动，则交换 INTSTITIAL<->COSITED。

1.4.1.4. Converting an NvCVImage Object to a Buffer that can be Encoded by NvEncoder

要通过NvEncoder将NvCVImage转换为在编码期间使用的像素格式，如有必要，请调用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>;
NvEncCudaPtr pEnc(new NvEncoderCuda(cuContext, dec.GetWidth(), dec.GetHeight(), NV_ENC_BUFFER_FORMAT_ARGB));
pEnc->CreateEncoder(&initializeParams);
//...
 
std::vector> 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. Allocating an NvCVImage Object Buffer

您可以使用NvCVImage分配构造函数或图像函数为NvCVImage对象分配缓冲区。在这两个选项中，当图像超出范围时，析构函数会自动释放缓冲区。

1.4.2.1. Using the NvCVImage Allocation Constructor to Allocate a Buffer

NvCVImage分配( allocation)构造函数创建一个已分配内存并已初始化的对象。有关详细信息，请参阅分配构造函数。

分配构造函数的最后三个可选参数决定了生成的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. Using Image Functions to Allocate a Buffer

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

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

   NvCVImage xfr;

2. 为图像分配或重新分配缓冲区。

   • 要分配缓冲区，请调用NvCVImage_Alloc()函数。

     当图像是状态结构的一部分时，以这种方式分配缓冲区，直到稍后您才会知道图像的大小。

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

     此函数检查分配的缓冲区，如果缓冲区足够大，则在释放缓冲区并调用NvCVImage_Alloc()之前对其进行调整。

1.4.3. Transferring Images Between CPU and GPU Buffers

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

1.4.3.1. Transferring Input Images from a CPU Buffer to a GPU Buffer

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

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

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()函数将源 CPU 缓冲区内容通过暂存 GPU 缓冲区复制到最终 GPU 缓冲区中。

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

1.4.3.2. Transferring Output Images from a GPU Buffer to a CPU Buffer

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

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

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

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. List of Properties for the AR SDK Features

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

1.5.1. Face Tracking Property Values

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

Table 2. Configuration Properities for Face Tracking

Property Name	Value
FeatureDescription	String is free-form text that describes the feature. The string is set by the SDK and cannot be modified by the user.
CUDAStream	The CUDA stream, which is set by the user.
ModelDir	String that contains the path to the folder that contains the TensorRT package files. Set by the user.
Temporal	Unsigned integer, 1/0 to enable/disable the temporal optimization of face detection. If enabled, only one face is returned. See Face Detection and Tracking for more information. Set by the user.

Table 3. Input Properties for Face Tracking

Property Name	Value
Image	Interleaved (or chunky) 8-bit BGR input image in a CUDA buffer of type NvCVImage. To be allocated and set by the user.

Table 4. Output Properties for Face Tracking

Property Name	Value
BoundingBoxes	NvAR_BBoxes structure that holds the detected face boxes. To be allocated by the user.
BoundingBoxesConfidence	An array of single-precision (32-bit) floating-point numbers that contains the confidence values for each detected face box. To be allocated by the user.

1.5.2. Landmark Tracking Property Values

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

Table 5. Configuration Properties for Landmark Tracking

Property Name	Value
FeatureDescription	String that describes the feature.
CUDAStream	The CUDA stream. Set by the user.
ModelDir	String that contains the path to the folder that contains the TensorRT package files. Set by the user.
BatchSize	The number of inferences to be run at one time on the GPU. The maximum value is 1.
Landmarks_Size	Unsigned integer, 68 or 126. Specifies the number of landmark points (X and Y values) to be returned. Set by the user.
LandmarksConfidence_Size	Unsigned integer, 68 or 126. Specifies the number of landmark confidence values for the detected keypoints to be returned. Set by the user.
Temporal	Unsigned integer, 1/0 to enable/disable the temporal optimization of landmark detection. If enabled, only one input bounding box is supported as the input. See Landmark Detection and Tracking for more information. Set by the user.

Table 6. Input Properties for Landmark Tracking

Property Name	Value
Image	Interleaved (or chunky) 8-bit BGR input image in a CUDA buffer of type NvCVImage. To be allocated and set by the user.
BoundingBoxes	NvAR_BBoxes structure that contains the number of bounding boxes that are equal to BatchSize on which to run landmark detection. If not specified as an input property, face detection is automatically run on the input image. See Landmark Detection and Tracking for more information. To be allocated by the user.

Table 7. Output Properties for Landmark Tracking

Property Name	Value
Landmarks	NvAR_Point2f array, which must be large enough to hold the number of points given by the product of NvAR_Parameter_Config(BatchSize) and NvAR_Parameter_Config(Landmarks_Size). To be allocated by the user.
Pose	NvAR_Quaternion array, which must be large enough to hold the number of quaternions equal to NvAR_Parameter_Config(BatchSize). To be allocated by the user.
LandmarksConfidence	An array of single-precision (32-bit) floating-point numbers, which must be large enough to hold the number of confidence values given by the product of the following: NvAR_Parameter_Config(BatchSize) NvAR_Parameter_Config(LandmarksConfidence_Size) To be allocated by the user.
BoundingBoxes	NvAR_BBoxes structure that contains the detected face through face detection performed by the landmark detection feature. See Landmark Detection and Tracking for more information. To be allocated by the user.

1.5.3. Face 3D Mesh Tracking Property Values

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

Table 8. Configuration Properties for Face 3D Mesh Tracking

Property Name	Value
FeatureDescription	String that describes the feature. This property is read-only.
ModelDir	String that contains the path to the face model, and the TensorRT package files. See Alternative Usage of the Face 3D Mesh Feature for more information. Set by the user.
CUDAStream	The CUDA stream. See Alternative Usage of the Face 3D Mesh Feature for more information. Set by the user.
Temporal	Unsigned integer, 1/0 to enable/disable the temporal optimization of face and landmark detection. See Alternative Usage of the Face 3D Mesh Feature for more information. Set by the user.
LandmarksConfidence_Size	Unsigned integer, 68 or 126. If landmark detection is run internally, the confidence values for the detected key points are returned. See Alternative Usage of the Face 3D Mesh Feature for more information.
ShapeEigenValueCount	The number of eigenvalues that describe the identity shape. Query this to determine how big the eigenvalue array should be, if that is a desired output. This property is read-only.
ExpressionCount	The number of expressions available in the chosen model. Query this to determine how big the expression coefficient array should be, if that is a desired output. This property is read-only.
VertexCount	The number of vertices in the chosen model. Query this property to determine how big the vertex array should be, where VertexCount is the number of vertices. This property is read-only.
TriangleCount	The number of triangles in the chosen model. Query this property to determine how big the triangle array should be, where TriangleCount is the number of triangles. This property is read-only.

Table 9. Input Properties for Face 3D Mesh Tracking

Property Name	Value
Width	The width of the input image buffer that contains the face to which the face model will be fitted. Set by the user.
Height	The height of the input image buffer that contains the face to which the face model will be fitted. Set by the user.
Landmarks	An NvAR_Point2f array that contains the landmark points of size NvAR_Parameter_Config(Landmarks_Size) that is returned by the landmark detection feature. If landmarks are not provided to this feature, an input image must be provided. See Alternative Usage of the Face 3D Mesh Feature for more information. To be allocated by the user.
Image	An interleaved (or chunky) 8-bit BGR input image in a CUDA buffer of type NvCVImage. If an input image is not provided as input, the landmark points must be provided to this feature as input. See Alternative Usage of the Face 3D Mesh Feature for more information. To be allocated by the user.

Table 10. Output Properties for Face 3D Mesh Tracking

Property Name	Value
FaceMesh	NvAR_FaceMesh structure that contains the output face mesh. To be allocated by the user.
RenderingParams	NvAR_RenderingParams structure that contains the rendering parameters for drawing the face mesh that is returned by this feature. To be allocated by the user.
Landmarks	An NvAR_Point2f array, which must be large enough to hold the number of points of size NvAR_Parameter_Config(Landmarks_Size). See Alternative Usage of the Face 3D Mesh Feature for more information. To be allocated by the user.
Pose	NvAR_Quaternion array pointer, to hold one quaternion. See Alternative Usage of the Face 3D Mesh Feature for more information. To be allocated by the user.
LandmarksConfidence	An array of single-precision (32-bit) floating-point numbers, which must be large enough to hold the number of confidence values of size NvAR_Parameter_Config(LandmarksConfidence_Size). See Alternative Usage of the Face 3D Mesh Feature for more information. To be allocated by the user.
BoundingBoxes	NvAR_BBoxes structure that contains the detected face that is determined internally. See Alternative Usage of the Face 3D Mesh Feature for more information. To be allocated by the user.
BoundingBoxesConfidence	An array of single-precision (32-bit) floating-point numbers that contain the confidence values for each detected face box. See Alternative Usage of the Face 3D Mesh Feature for more information. To be allocated by the user.
ShapeEigenValues	Optional: The array into which the shape eigenvalues will be placed, if desired. Query ShapeEigenValueCount to determine how big this array should be. To be allocated by the user.
ExpressionCoefficients	Optional: The array into which the expression coefficients will be placed, if desired. Query ExpressionCount to determine how big this array should be. To be allocated by the user.

1.5.4. Body Detection Property Values

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

Table 11. Configuration Properties for Body Dection Tracking

Property Name	Name
FeatureDescription	String is free-form text that describes the feature. The string is set by the SDK and cannot be modified by the user.
CUDAStream	The CUDA stream, which is set by the user.
ModelDir	String that contains the path to the folder that contains the TensorRT package files. Set by the user.
Temporal	Unsigned integer, 1/0 to enable/disable the temporal optimization of body detection. Set by the user.

Table 11. Configuration Properties for Body Dection Tracking

Property Name	Name
FeatureDescription	String is free-form text that describes the feature. The string is set by the SDK and cannot be modified by the user.
CUDAStream	The CUDA stream, which is set by the user.
ModelDir	String that contains the path to the folder that contains the TensorRT package files. Set by the user.
Temporal	Unsigned integer, 1/0 to enable/disable the temporal optimization of body detection. Set by the user.

Table 13. Output Properties for Body Detection

Property Name	Value
BoundingBoxes	NvAR_BBoxes structure that holds the detected body boxes. To be allocated by the user.
BoundingBoxesConfidence	An array of single-precision (32-bit) floating-point numbers that contains the confidence values for each detected body box. To be allocated by the user.

1.5.5. 3D Body Pose Keypoint Tracking Property Values

下表列出了 3D Body Pose Keypoint Tracking 的配置、输入和输出属性的值。

Table 14. Configuration Properties for 3D Body Pose Keypoint Tracking

Property Name	Value
FeatureDescription	FeatureDescription String that describes the feature.
CUDAStream	The CUDA stream. Set by the user.
ModelDir	String that contains the path to the folder that contains the TensorRT package files. Set by the user.
BatchSize	The number of inferences to be run at one time on the GPU. The maximum value is 1.
Mode	Unsigned integer, 0 or 1. Default is 1. Selects the High Performance (1) mode or High Quality (0) mode Set by the user.
UseCudaGraph	Bool, True or False. Default is True Flag to use CUDA Graphs for optimization. Set by the user.
FocalLength	Float. Default is 800.79041 Specifies the focal length of the camera to be used for 3D Body Pose. Set by the user.
Temporal	Unsigned integer and 1/0 to enable/disable the temporal optimization of Body Pose tracking. Set by the user.
NumKeyPoints	Unsigned integer. Specifies the number of keypoints available, which is currently 34.
ReferencePose	NvAR_Point3f array, which contains the reference pose for each of the 34 keypoints. Specifies the Reference Pose used to compute the joint angles.

Table 15. Input Properties for 3D Body Pose Keypoint Tracking

Property Name	Value
Image	Interleaved (or chunky) 8-bit BGR input image in a CUDA buffer of type NvCVImage. To be allocated and set by the user.
BoundingBoxes	NvAR_BBoxes structure that contains the number of bounding boxes that are equal to BatchSize on which to run 3D Body Pose detection. If not specified as an input property, body detection is automatically run on the input image. To be allocated by the user.

Table 16. Output Properties for 3D Body Pose Keypoint Tracking

Property Name	Value
Keypoints	NvAR_Point2f array, which must be large enough to hold the 34 points given by the product of NvAR_Parameter_Config(BatchSize) and 34. To be allocated by the user.
Keypoints3D	NvAR_Point3f array, which must be large enough to hold the 34 points given by the product of NvAR_Parameter_Config(BatchSize) and 34. To be allocated by the user.
JointAngles	NvAR_Quaternion array, which must be large enough to hold the 34 joints given by the product of NvAR_Parameter_Config(BatchSize) and 34. They represent the local rotation (in Quaternion) of each joint with reference to the ReferencePose. To be allocated by the user.
KeyPointsConfidence	An array of single-precision (32-bit) floating-point numbers, which must be large enough to hold the number of confidence values given by the product of the following: NvAR_Parameter_Config(BatchSize) 34 To be allocated by the user.
BoundingBoxes	NvAR_BBoxes structure that contains the detected body through body detection performed by the 3D Body Pose feature. To be allocated by the user.

1.6. Using the AR Features

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

1.6.1. Face Detection and Tracking

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

1.6.1.1. Face Detection for Static Frames (Images)

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

此示例使用输入图像缓冲区和输出内存运行人脸检测 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. Face Tracking for Temporal Frames (Videos)

如果启用了Temporal ，例如，当您处理视频帧而不是图像时，则只返回一个人脸。最大的人脸出现在第一帧，随后在随后的帧中跟踪该人脸。

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

1.6.2. Landmark Detection and Tracking

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

1.6.2.1. Landmark Detection for Static Frames (Images)

通常，特征点检测功能的输入是输入图像和一批（最多 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 output buffer to hold detected facial keypoints
std::vector 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. Alternative Usage of Landmark Detection

但是，如Landmark Tracking Property Values中所述，Landmark Detection AR 功能支持一些可选参数，这些参数决定了该功能的运行方式。

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

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

1.6.2.3. Landmark Tracking for Temporal Frames (Videos)

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

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

注意：内部确定的边界框可以从此功能中查询，但不是该功能运行所必需的。

此示例使用 Landmark Detection AR 功能直接从图像中获取特征点，而无需先显式运行人脸检测：

//Set input image buffer
NvAR_SetObject(landmarkDetectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
 
//Set output memory for landmarks
std::vector 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));
 
//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. Face 3D Mesh and Tracking

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

1.6.3.1. Face 3D Mesh for Static Frames (Images)

通常，人脸 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. Alternative Usage of the Face 3D Mesh Feature

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

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

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

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

1.6.3.3. Face 3D Mesh Tracking for Temporal Frames (Videos)

如果设置了 Temporal 标志并且在内部运行人脸和关键点检测，则这些特征将针对时间相关的帧进行优化
这意味着将跨帧跟踪面部和面部关键点，并且如果请求，将仅返回一个边界框作为输出。如果显式调用了地标检测和/或人脸检测功能，则人脸 3D 网格功能不支持时间标志。在这种情况下，您必须直接向这些功能提供标志。
注意：内部确定的面部关键点和/或面部边界框可以从此功能中查询，但不是该功能运行所必需的。
此示例使用 Mesh Tracking AR 功能直接从图像中获取人脸网格，无需显式运行 Landmark Detection 或 Face Detection：

//Set input image buffer instead of providing facial keypoints
NvAR_SetObject(landmarkDetectHandle, NvAR_Parameter_Input(Image), &inputImageBuffer, sizeof(NvCVImage));
 
//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));
 
//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. 3D Body Pose Tracking

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

3D Body Pose Tracking 由以下部分组成：

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

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

1.6.4.1. 3D Body Pose Tracking for Static Frames (Images)

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

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

//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 Body Keypoint Detection 的输入是输入图像。它输出 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 keypoints;
std::vector keypoints3D;
std::vector jointAngles;
std::vector 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.4.2. 3D Body Pose Tracking for Temporal Frames (Videos)

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

此示例使用 3D Body Pose Tracking AR 功能直接从图像中获取 3D Body Pose Keypoints：

//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 keypoints;
std::vector keypoints3D;
std::vector jointAngles;
std::vector 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.7. Using Multiple GPUs

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

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

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. Default Behavior in Multi-GPU Environments

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. Selecting the GPU for AR SDK Processing in a Multi-GPU Environment

您的应用程序可能设计为仅通过在多 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. Selecting Different GPUs for Different Tasks

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

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

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

2. 通过对每个 GPU 循环执行以下操作，获取每个 GPU 的属性，并确定它是否是每个任务的最佳 GPU：

   • 调用cudaSetDevice()设置当前 GPU。
   • 调用cudaGetDeviceProperties()获取当前 GPU 的属性。
   • 要确定 GPU 是否是每个特定任务的最佳 GPU，请在应用程序中使用自定义代码来分析cudaGetDeviceProperties()检索到的属性。
     此示例使用计算能力来确定是否应分析 GPU 的属性并确定当前 GPU 是否是应用视频效果滤镜的最佳 GPU。仅当计算能力为 7.5 或 8.6 时才分析 GPU 的属性，这表示 GPU 分别基于 NVIDIA Turing™ GPU 架构或 NVIDIA Ampere 架构。

  // 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.  	In the loop to complete the application’s tasks, select the best GPU for each task before performing the task.
a).	Call cudaSetDevice() to select the GPU for the task.
b).	Make all the function calls required to perform the task.
In this way, you select the best GPU for each task only once without setting the GPU for every function call.
This example selects the best GPU for rendering a game and uses custom code to render the game. It then selects the best GPU for applying a video effect filter before calling the NvCVImage_Transfer() and NvAR_Run() functions to apply the filter, avoiding the need to save and restore the GPU for every NVIDIA AR SDK API call.
// Select the best GPU for each task and perform the task.
while (!done) {
  ...
  cudaSetDevice(gpuGame);
  RenderGame();
  cudaSetDevice(gpuARSDK);
  err = NvAR_Run(eff, 1);
  ...
}