函数：get_input_dynamic_gear_count
函数：get_cur_output_dims
| C函数原型 | aclError aclmdlGetCurOutputDims(const aclmdlDesc *modelDesc, size_t index, aclIODims *dims) |
|---|---|
| Python函数 | dims, ret = acl.mdl.get_cur_output_dims(model_desc, index**)** |
| 函数功能 | 根据模型描述信息获取指定的模型输出tensor的实际维度信息。同步接口。 |
| 输入说明 | model_desc：int，aclmdlDesc类型数据的指针地址。 需提前调用acl.mdl.create_desc接口创建aclmdlDesc类型的数据。 index：int，指定获取第几个输出的Dims，index值从0开始。 |
| 返回值说明 | dims：dict，输出实际维度信息。 若tensor的name长度大于127，则在输出dims.name时，pyACL会将tensor的name转换为“acl_modelId_${id}input${index}${随机字符串} ”格式（如果转换后的tensor的name与模型中已有的tensor的name冲突，则会在转换后的name尾部增加“${随机字符串} ”，否则不会增加随机字符串），并在转换后的name与原name之间建立映射关系，用户可调用acl.mdl.get_tensor_real_name接口，传入转换后的name，获取原name（若向接口传入原name，则获取的还是原name）；若tensor的name长度小于或等于127，则在输出的dims.name时，按tensor的name输出。 ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 动态Shape（动态Batch或动态分辨率或动态维度（ND格式））场景下，如果用户已调用acl.mdl.set_dynamic_batch_size设置Batch、或调用acl.mdl.set_dynamic_hw_size接口设置输入图片的宽高、或调用acl.mdl.set_input_dynamic_dims接口设置某动态维度的值，则可通过该接口获取指定模型输出tensor的实际维度信息；如果用户未调用acl.mdl.set_dynamic_batch_size接口、或acl.mdl.set_dynamic_hw_size接口、或acl.mdl.set_input_dynamic_dims接口，则通过该接口可获取最大档的维度信息。 非动态Shape场景下，通过该接口获取指定的模型输出tensor的维度信息。 |
父主题： aclmdlDesc
函数：get_first_aipp_info
| C函数原型 | aclError aclmdlGetFirstAippInfo(uint32_t modelId, size_t index, aclAippInfo *aippInfo) |
|---|---|
| Python函数 | aipp_info, ret = acl.mdl.get_first_aipp_info(model_id, index) |
| 函数功能 | 获取模型静态AIPP的配置信息。同步接口。 AIPP支持的几种操作的计算方式及其计算顺序如下：抠图->色域转换->缩放（当前版本不支持缩放）->减均值/归一化->padding。 |
| 输入说明 | model_id：int，模型ID。 调用acl.mdl.load_from_file接口/acl.mdl.load_from_mem接口/acl.mdl.load_from_file_with_mem接口/acl.mdl.load_from_mem_with_mem接口加载模型成功后，会返回模型ID。 index：int，指定模型的第几个输入。 |
| 返回值说明 | aipp_info：dict，获取指定输入上静态AIPP的配置信息。 ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 如果使用本接口获取模型中动态AIPP的信息，只能获取aclAippInfo中如下参数的值：srcFormat、srcDatatype、srcDimNum、shapeCount、outDims，其它参数值无效。 aclAippInfo结构体以字典返回，字典中的key对应结构体的成员名。 |
父主题： aclmdlDesc
函数：get_input_dynamic_gear_count
| C函数原型 | aclError aclmdlGetInputDynamicGearCount(const aclmdlDesc *modelDesc, size_t index, size_t *gearCount) |
|---|---|
| Python函数 | gear_count, ret = acl.mdl.get_input_dynamic_gear_count(model_desc, index) |
| 函数功能 | 根据模型描述信息获取模型的输入所支持的动态维度档位数。同步接口。 |
| 输入说明 | model_desc：int，aclmdlDesc类型数据的指针地址。 index：int，预留参数，当前未使用，固定设置为-1。 |
| 返回值说明 | gear_count：int， 动态维度档位数。 例如，模型的输入tensor是4维，在模型转换时通过--dynamic_dims参数设置的分档为“1,3,224,224;2,3,224,224;1,3,256,256”,那么通过该接口获取的动态维度档位数为3。 ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 如果模型构建时没有设置动态维度的分档，那么通过该接口获取的动态维度档位数为0。模型构建的详细说明请参见模型构建。 |
父主题： aclmdlDesc
函数：get_input_dynamic_dims
| C函数原型 | aclError aclmdlGetInputDynamicDims(const aclmdlDesc *modelDesc, size_t index, aclmdlIODims *dims, size_t gearCount) |
|---|---|
| Python函数 | dims_out, ret = acl.mdl.get_input_dynamic_dims(model_desc, index, gear_count) |
| 函数功能 | 根据模型描述信息获取模型的输入所支持的动态维度信息。同步接口。 |
| 输入说明 | model_desc：int，aclmdlDesc类型数据的指针地址。 index：int，预留参数，当前未使用，固定设置为-1。 gear_count：int，模型支持的动态维度档位数，需要先通过acl.mdl.get_input_dynamic_gear_count接口获取。 |
| 返回值说明 | dims_out：list，获取输入的动态维度信息。 dims_out参数是一个列表，模型有几个输入，则该列表就有几个元素。列表中的每个元素都是一个aclmdlIODims的字典，aclmdlIODims字典中的dims是一个列表，该列表中的每个元素对应每一档中的具体值。 例如： text<br>dims_out, ret = acl.mdl.get_input_dynamic_dims(model_desc, -1, gear_count)<br>ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 只有在模型转换时通过--dynamic_dims参数设置了分档信息后，才可以调用该接口获取动态维度信息。 例如，模型有三个输入，分别为data(1, 1, 40, -1)，label(1, -1)，mask(-1, -1) ， 其中-1表示动态可变。在模型转换时，dynamic_dims参数的配置示例为：--dynamic_dims="20,20,1,1; 40,40,2,2; 80,60,4,4"，则通过本接口获取的动态维度信息为（aclmdlIODims字典内的name暂不使用）： - 第0档： - aclmdlIODims内dimCount：8，表示所有输入tensor的维度数量之和 - aclmdlIODims内的dims：“1,1,40,20,1,20,1,1”，表示data(1,1,40,20)+label(1,20)+mask(1,1) - 第1档： - aclmdlIODims内dimCount：8，表示所有输入tensor的维度数量之和 - aclmdlIODims内的dims：“1,1,40,40,1,40,2,2”，表示data(1,1,40,40)+label(1,40)+mask(2,2) - 第2档： - aclmdlIODims内dimCount：8，表示所有输入tensor的维度数量之和 - aclmdlIODims内的dims：“1,1,40,80,1,60,4,4”，表示data(1,1,40,80)+label(1,60)+mask(4,4) |
父主题： aclmdlDesc
函数：get_op_attr
| C函数原型 | const char *aclmdlGetOpAttr(aclmdlDesc *modelDesc, const char *opName, const char *attr) |
|---|---|
| Python函数 | attrValue = acl.mdl.get_op_attr(modelDesc, opName, attr) |
| 函数功能 | 获取整网中某个模型中某个算子的属性的值。同步接口。 |
| 输入说明 | **modelDesc：**aclmdlDesc类型的指针地址。 需提前调用acl.mdl.create_desc接口创建aclmdlDesc类型的数据，再调用 acl.mdl.get_desc接口根据模型ID获取到对应的aclmdlDesc类型的数据。 **opName：**算子名称。 **attr：**算子属性。 当前仅支持_datadump_original_op_names属性，用于记录某个算子是由哪些算子融合得到的。通过本接口获取到的_datadump_original_op_names属性值格式为[opName1_len]opName1…..[opNameN_len]opNameN，opNameN_len表示算子名称字符串的长度。 _datadump_original_op_names属性值示例如下，表示某个融合算子由scale2c_branch2c、bn2c_branch2c、res2c_branch2c、res2c、res2c_relu这五个算子融合而成的，算子名称字符串的长度分别为16、13、14、5、10： text<br>[16]scale2c_branch2c[13]bn2c_branch2c[14]res2c_branch2c[5]res2c[10]res2c_relu<br> |
| 返回值说明 | attrValue：返回属性值的字符串，若opName或者attr属性不存在、或者attr属性值为空，均返回空字符串。 若调用该接口失败，则返回None。 |
| 约束说明 | 无 |
父主题： aclmdlDesc
总体说明
多版本接口差异
- 本手册中媒体数据处理V1版本与媒体数据处理V2版本的接口功能范围相同，都是描述处理媒体数据的接口，用于实现抠图、图片缩放、格式转换等功能，但两套接口不能混用。
- 建议使用V2版本中的接口，保证后续版本接口功能以及业务的连续演进。
- V1版本中的接口是为了兼容旧版本，保证使用该部分接口的用户能继续使用，后续版本不再演进。
功能说明
本章节介绍媒体数据处理V1版本（DVPP，Digital Vision Pre-Processing）的功能，如表1所示。
表1 功能说明
| 功能 | 说明 |
|---|---|
| VPC（Vision Preprocessing Core） | 负责图像处理功能，支持对图片做抠图、缩放、格式转换等操作，详细描述请参见功能说明。 |
| JPEGD（JPEG Decoder） | 负责完成图像解码功能，将.jpg、.jpeg、.JPG、.JPEG图片解码成YUV格式图片，详细描述请参见功能及约束说明。 |
| JPEGE（JPEG Encoder） | 负责完成图像编码功能，将YUV格式图片编码成.jpg图片，详细描述请参见功能及约束说明。 |
| VDEC（Video Decoder） | 负责视频解码，详细描述请参见功能及约束说明。 |
| VENC（Video Encoder） | 负责视频编码，详细描述请参见功能及约束说明。 |
| PNGD（PNG decoder） | 负责PNG格式图片的解码，详细描述请参见功能及约束说明。 |
功能支持度说明
昇腾AI处理器对媒体数据处理V1版本各功能的支持度如表2所示。
表2 功能支持度说明
| 昇腾AI处理器 | VPC | JPEGD | JPEGE | PNGD | VDEC | VENC |
|---|---|---|---|---|---|---|
| Atlas 200/500 A2推理产品 | √ | √ | √ | √ | √ | √ |
整体约束说明
使用本章中介绍的接口，有以下注意点：
-
关于异步接口：
对于本章介绍的异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，对于有依赖的接口，为确保能按序执行任务，建议用户在多个接口中指定同一个stream，因为同一个stream中的任务按接口调用顺序执行。
在调用异步口对图片进行解码、抠图、缩放等操作时，如果任务之间有依赖，一定要调用acl.rt.synchronize_stream接口确保在同一个Stream中的任务按序执行。
从性能角度考虑，建议一个stream上下发多个异步媒体数据处理任务后，执行一次acl.rt.synchronize_stream接口。
调用异步接口后，不能马上释放资源，需调用同步等待接口（例如，acl.rt.synchronize_stream）确保Device侧任务执行完成后才能释放。
-
关于内存申请/释放：
- 实现媒体数据处理的VPC、JPEGD、JPEGE等功能前，若需要申请Device上的内存存放输入或输出数据，需调用acl.media.dvpp_malloc申请内存、调用acl.media.dvpp_free接口释放内存。
- 调用1申请出来的内存可以满足媒体数据处理的要求，也可以在其它任务中使用，例如，从性能角度，为了减少拷贝，媒体数据处理的输出作为模型推理的输入，实现内存复用。
- 但由于媒体数据处理访问的地址空间有限，为确保媒体数据处理时内存足够，除媒体数据处理功能外的其它功能（例如，模型加载），建议调用内存管理章节下的acl.rt.malloc接口、或acl.rt.malloc_host接口、或acl.rt.malloc_cached接口申请内存。
-
关于通道的要求：
实现媒体数据处理的各功能前，必须调用接口创建对应功能的通道，创建通道的接口请参见通道创建与释放。通道的创建与销毁会涉及资源的申请与释放，反复创建与销毁通道会影响业务性能，因此建议根据实际场景管理通道，例如，如果有持续VPC图片处理，则创建VPC的通道后，等到所有VPC功能调用完成后，再销毁该VPC通道。
通道数量多，会影响Device的CPU占用率和内存占用，通道数量建议参考各功能章节下的的性能指标的路数。
在Atlas 200/500 A2推理产品上，各功能的通道数有一定的限制，VPC的通道数最多128，JPEGD的通道数最多128，VDEC的通道数最多128，JPEGE的通道数最多128，VENC的通道数最多128，PNGD的通道数最多128。创建通道的接口请参见通道创建与释放。
:::note 说明 **对于Atlas 200/500 A2推理产品，**昇腾虚拟化实例（Ascend Virtual Instance）场景下，如果通道总数不为整数，则向下取整：
- VPC通道总数最多128。
- VDEC通道 = ( 被分配的VDEC硬件单元 / VDEC硬件单元 ) * 128，如果通道总数不为整数，则向下取整。JPEGD的通道数不随算力影响，但JPEGD+VDEC的总通道数最大128。
- VENC通道 = ( 被分配的VENC硬件单元 / VENC硬件单元 ) * 128，如果通道总数不为整数，则向下取整。JPEGE的通道数不随算力影响，但JPEGE+VENC的总通道数最大128。 :::
父主题： 媒体数据处理V1
在线提单