Skip to content

media_data_processing.md

Latest commit

 

History

History
1630 lines (989 loc) · 56.2 KB

media_data_processing.md

File metadata and controls

1630 lines (989 loc) · 56.2 KB
Raw

媒体数据处理

Tensor

类说明

Tensor数据类，作为模型推理的输入与输出的数据结构。

支持的型号

Atlas 200I/500 A2 推理产品

Atlas 推理系列产品

Tensor

[!NOTICE] 多个Tensor对象按batch维进行concat操作时请使用base.batch_concat()函数，具体使用方式请参见batch_concat(inputs)。

函数功能

numpy数组转换为Tensor。

Tensor数据结构接收了作为参数（buffer）传进来的一段缓冲区内存地址，因此在使用numpy数组进行数据预处理并转为Tensor时，要注意预处理的过程中是否对内存进行修改。

例如：transpose()函数作用是调换数组的索引值，但是该函数实际未对数据内存地址进行重新排列，仅在获取numpy数组时返回转换后的值。如将该numpy数组转为Tensor，实际获得的是未经重新排列的Tensor。（即numpy数组为transpose()转置后数组，Tensor为transpose()转置前数组。）

如需使用例如transpose()等不改变内存排列的函数，可以在transpose()处理后使用如numpy.ascontiguousarray()等接口来重新排列内存数据，使得转换后的Tensor对象数据和期望得到的转置后数组一致。

函数原型

Tensor(buffer: ndarray)

输入参数说明

参数名 类型 说明
buffer numpy数组 待转换为Tensor的numpy数组。

返回参数说明

Tensor对象。

to_device

函数功能

移动Tensor到Device内存中。

函数原型

to_device(deviceId: int)

输入参数说明

参数名 类型 说明
deviceId int Device设备的ID号。

抛异常接口

分配Tensor内存失败及拷贝到Device侧失败，抛出Runtime异常。

to_host

函数功能

移动Tensor到Host内存中。

函数原型

to_host()

抛异常接口

分配Tensor内存失败及拷贝到Host侧失败，抛出Runtime异常。

Tensor类的属性列表

属性名 说明 备注
device Tensor所在Device的ID -1表示运行在Host侧，1表示设备号1，2表示设备号2，以此类推。
dtype Tensor数据类型 base.dtype数据类型。
shape Tensor的维度信息 返回的是list数据类型。

set_tensor_value

函数功能

设置Tensor的值，支持dtype.int32、dtype.uint8、dtype.float16、dtype.float32类型。

  • 请注意数据类型与数据范围。
  • Tensor对象需在Device侧且数据类型与调用的set_tensor_value的方法匹配。

函数原型

set_tensor_value(value: float, dataType: dtype)

输入参数说明

参数名 类型 说明
value float 需要设置的值，不可为空。
dataType dtype枚举类型 dataType: dtype转换类型，不可为空，支持的输入有：dtype.float16,dtype.float32,dtype.uint8,dtype.int32。

返回参数说明

返回进行张量设置值后的Tensor类数据。

Image

类说明

作为图像处理类，主要开放图像编解码、缩放和抠图等接口。

支持的型号

Atlas 200I/500 A2 推理产品

Atlas 推理系列产品

Image

函数功能

  • 构造一个空的Image对象。
  • 从Host侧的numpy的ndarray转为Image对象。

函数原型

Image()
Image(b: ndarray, format: image_format, imageSizeInfo: Tuple = DEFAULT_IMAGE_SIZE_INFO)

输入参数说明

参数名 类型 说明
b ndarray 构造Image的numpy数组，各元素类型为np.uint8且形状为3维，依次表示图片的HWC（高、宽、通道数）。
format image_format 图像色域格式，支持以下色域类型。
  • base.yuv_400
  • base.rgb
  • base.bgr
  • base.rgba
  • base.bgra
  • base.argb
  • base.abgr

    • b（输入ndarray）形状中的通道数（C）需要与色域类型一致，各色域类型对应通道数参见如下。
  • yuv_400为1。
  • bgr、rgb为3。
  • rgba、bgra、argb、abgr为4。
    		•
    imageSizeInfo Tuple(Size, Size) 图像有效宽高与对齐后宽高的组合，有效宽、高应不超过对齐后的宽、高，输入方式参见如下。
    tuple(有效宽高，对齐后的宽高)
  • 有效宽、高取值范围为[6, 8192]。
  • 对齐后宽、高取值范围为[16, 8192]，其中宽为16的倍数、高为2的倍数。
  • b（输入ndarray）形状中的高宽需要与有效宽高和对齐宽高其中之一保持一致。
  • 默认值为DEFAULT_IMAGE_SIZE_INFO，其中有效宽高与对齐后宽高均为(0, 0)，若该参数为默认值，则自动根据b的形状获取有效宽高和对齐宽高。
    		•

    Note

    • 从opencv读取图片转换的ndarray，若形状为WHC（宽，高，通道数），需要进行转置为HWC（高，宽，通道数）之后进行构造。
    • 从get_tensor/to_tensor/get_original_tensor接口获取的tensor，转换为ndarray后，形状为NHWC（个数，高，宽，通道数）或NHW（个数，高，宽），需要根据实际情况截取或扩展到HWC之后进行构造。

    返回参数说明

    Image对象。

    to_tensor

    函数功能

    将Image对象转换为Tensor类对象。

    函数原型

    to_tensor()

    返回参数说明

    返回Tensor。

    get_tensor

    函数功能

    获取Tensor类对象。

    函数原型

    get_tensor()

    返回参数说明

    返回Tensor。

    get_original_tensor

    函数功能

    获取图片有效范围的Tensor类对象。

    支持以下图片色域类型。

    • base.yuv_400
    • base.rgb
    • base.bgr
    • base.rgba
    • base.bgra
    • base.argb
    • base.abgr

    如需将图片转换为ndarray时，请将图片在Host侧通过该接口转为Tensor，再转为ndarray。

    函数原型

    get_original_tensor()

    返回参数说明

    返回Tensor。

    to_device

    函数功能

    搬移image到Device内存中。

    函数原型

    to_device(deviceId: int)

    输入参数说明

    参数名 类型 说明
    deviceId int Device设备的ID号。

    抛异常接口

    调用Tensor的to_device函数失败，抛出Runtime异常。

    to_host

    函数功能

    搬移image到Host内存中。

    函数原型

    to_host()

    抛异常接口

    调用Tensor的to_host函数失败，抛出Runtime异常。

    serialize

    函数功能

    将图像内存数据及元数据序列化后落盘保存为文件。

    函数原型

    serialize(filePath: str, forceOverwrite: bool = False);

    输入参数说明

    参数名 类型 说明
    filePath str 序列化后的数据文件保存路径（包括文件名称），不支持软链接。
    forceOverwrite bool 保存时是否强制覆盖已有文件，默认为False，不覆盖。

    unserialize

    函数功能

    将serialize中保存的落盘数据文件加载到内存中，需指定文件名称及具体路径。

    函数原型

    unserialize(filePath: str);

    输入参数说明

    参数名 类型 说明
    filePath str 落盘数据文件保存路径，输入文件大小支持范围为(0, 4GB]。

    dump_buffer

    函数功能

    将图像内存数据落盘到二进制文件，需要指定文件名称及具体路径。

    函数原型

    dump_buffer(filePath: str, forceOverwrite: bool = False);

    输入参数说明

    参数名 类型 说明
    filePath str 落盘数据文件路径（包含文件名称），不支持软链接。
    forceOverwrite bool 保存时是否强制覆盖已有文件，默认为False，不覆盖。

    Image类的属性列表

    属性名 说明
    device Image所在Device的ID。
    height 返回Image类对齐后的高。
    width 返回Image类对齐后的宽。
    original_height 返回Image类的原始高。
    original_width 返回Image类的原始宽。
    format 返回图像的格式。

    ImageProcessor

    类说明

    作为图像处理类，主要开放图像编解码、缩放和抠图等接口。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    convert_format

    函数功能

    ImageProcessor类的色域转换接口，使用该接口申请的Image内存无需用户管理，由内部管理释放。当前接口仅能够在Atlas 推理系列产品和Atlas 800I A2推理产品环境上调用。

    函数原型

    convert_format(inputImage: Image, outputFormat: image_format)

    参数说明

    参数名 类型 说明
    inputImage Image类 输入转换前的Image类。decode接口和其他VPC接口获取的Image类可以直接作为输入。
  • 输入图片宽高范围应该在32 * 6 ~ 4096 * 4096之间。
  • 当前输入Image类的格式支持YUV_SP_420、YVU_SP_420、RGB_888、BGR_888。
    		•
    outputFormat image_format枚举类 色域转换的目标格式，支持YUV_SP_420、YVU_SP_420、RGB_888、BGR_888四种格式对应的枚举类。
  • 输出Image类的宽自动与16对齐，高与2对齐，因此宽高范围为：32 * 6 ~ 4096 * 4096。
  • 输出Image类宽高保持与输入Image类一致。
  • 请确保转换前的格式与转换后的格式不同。
    		•

    返回参数说明

    返回转换输出Image对象。

    crop

    函数功能

    ImageProcessor类的图像抠图接口，输入输出格式、分辨率范围、对齐方式请参见Crop。

    接口使用流程请参考抠图。

    函数原型

    crop(inputImage: Image, cropRectVec: List)

    输入参数说明

    参数名 类型 说明
    inputImage Image类 输入抠图前的Image类。
    cropRectVec List[Rect] 输入图像的抠图坐标框列表。

    返回参数说明

    返回抠图后的Image类列表List[Image]。

    抛异常接口

    抠图失败，抛出Runtime异常。

    crop

    函数功能

    ImageProcessor类的图像抠图接口，输入输出格式、分辨率范围、对齐方式请参见Crop。

    接口使用流程请参考抠图。

    函数原型

    crop(inputImageVec: List, cropRectVec: List)

    输入参数说明

    参数名 类型 说明
    inputImageVec List[Image] 输入抠图前的Image类列表。
    cropRectVec List[Rect] 输入图像的抠图坐标框列表。

    返回参数说明

    返回抠图后的Image类列表List[Image]。

    抛异常接口

    抠图失败，抛出Runtime异常。

    crop_paste

    函数功能

    ImageProcessor类的图像抠图并贴图接口。接口使用流程请参考抠图贴图。

    1. 从“inputImage”中抠取一块图像，缩放至指定贴图区域的大小。
    2. 将抠图后的图片贴到“pastedImage”的指定贴图区域。输入输出格式、分辨率范围、对齐方式请参见CropAndPaste。

    函数原型

    crop_paste(inputImage: Image, cropPasteRect: Tuple, pastedImage: Image)

    输入参数说明

    参数名 类型 说明
    inputImage Image类 输入抠图前的Image类。
    cropPasteRect Tuple(Rect, Rect) 输入图像的抠图参数。第一个Rect对应抠图参数，第二个Rect对应贴图参数。
    pastedImage Image类 被贴图的Image类。

    抛异常接口

    抠图并贴图失败，抛出Runtime异常。

    crop_resize

    函数功能

    ImageProcessor类的图像抠图并缩放接口，输入输出格式、分辨率范围、对齐方式请参见CropResize。

    接口使用流程请参考抠图缩放。

    函数原型

    crop_resize(inputImage: Image, cropResizeVec: List)

    输入参数说明

    参数名 类型 说明
    inputImage Image类 输入抠图缩放前的Image类。
    cropResizeVec List[Tuple(Rect, Size)] 输入图像的抠图缩放参数列表。Rect为抠图坐标框，Size为缩放宽高。

    返回参数说明

    返回抠图缩放后的Image类列表List[Image]。

    抛异常接口

    抠图缩放失败，抛出Runtime异常。

    decode

    函数功能

    ImageProcessor类的图片解码接口，输入输出格式、分辨率范围、对齐方式请参见Decode。

    接口使用流程请参考图片解码。

    函数原型

    decode(inputPath: str, decodeFormat: image_format)

    输入参数说明

    参数名 类型 说明
    inputPath str 输入待解码的图片路径。
    decodeFormat image_format枚举类 输入解码后图片的格式。（PNG格式解码无需设置。）

    返回参数说明

    返回解码后的Image类。

    抛异常接口

    图片路径错误、解码格式错误、解码失败，抛出Runtime异常。

    decode_bytes

    函数功能

    ImageProcessor类的图片解码接口，输入输出格式、分辨率范围、对齐方式请参见Decode。

    接口使用流程请参考图片解码。

    函数原型

    decode_bytes(data: bytes, dataSize: int, decodeFormat: image_format)

    输入参数说明

    参数名 类型 说明
    data bytes 输入解码前的二进制数据。
    dataSize int 二进制数据有效长度。需与输入数据长度保持一致。
    decodeFormat image_format枚举类 输入解码后图片的格式（PNG格式解码时无需设置），默认为base.nv12。

    返回参数说明

    返回解码后的image类。

    抛异常接口

    数据类型或长度不匹配、解码格式错误、解码失败，抛出Runtime异常。

    encode

    函数功能

    ImageProcessor类的图片编码接口，输入输出格式、分辨率范围、对齐方式请参见Encode。

    接口使用流程请参考图片编码。

    函数原型

    encode(inputImage: Image, savePath: str, encodeLevel: int)

    输入参数说明

    参数名 类型 说明
    inputImage Image类 输入编码前的Image类。
    savePath str 输入编码后保存的图片路径，文件后缀名限制为 jpg，编码后图片保存至该路径下。
    encodeLevel int 默认为100，Atlas 200I/500 A2 推理产品、Atlas 推理系列产品的范围为[1, 100]。

    抛异常接口

    图片路径错误、编码级别错误、编码失败，抛出Runtime异常。

    encode_bytes

    函数功能

    ImageProcessor类的图片编码接口，输入输出格式、分辨率范围、对齐方式请参见Encode。

    接口使用流程请参考图片编码。

    函数原型

    encode_bytes(inputImage: Image, encodeLevel: int)

    输入参数说明

    参数名 类型 说明
    inputImage Image 输入编码前的Image类。
    encodeLevel int 默认为“100”，Atlas 200I/500 A2 推理产品、Atlas 推理系列产品的范围为[1,100]。

    返回参数说明

    编码后的二进制bytes数据。

    抛异常接口

    编码级别错误、编码失败，抛出Runtime异常。

    ImageProcessor

    函数功能

    ImageProcessor类的构造函数，若因内存不足，或无法识别芯片等构造失败的场景会抛出Runtime异常。

    函数原型

    ImageProcessor(deviceId: int = 0)

    输入参数说明

    参数名 类型 说明
    deviceId int 图像处理类部署的芯片，默认为0号芯片。取值范围：[0, 识别到的芯片个数 - 1]

    返回参数说明

    ImageProcessor对象。

    padding

    函数功能

    ImageProcessor类的图像处理补边接口，输入输出格式、分辨率范围请参见Padding。

    接口使用流程请参考补边。

    函数原型

    padding(inputImage: Image, padDim: Dim, color: Color, borderType: borderType)

    输入参数说明

    参数名 类型 说明
    inputImage Image类 输入补边前的Image类。
    padDim Dim类 输入图像补边的尺寸。
    color Color类 输入补边三通道颜色，仅在borderType设置为BORDER_CONSTANT时有效。
    borderType borderType参数枚举类 输入补边方式。具体请参见borderType补边方式枚举类型。

    返回参数说明

    返回补边后的Image类。

    抛异常接口

    补边失败，抛出Runtime异常。

    resize

    函数功能

    ImageProcessor类的图像缩放接口，输入输出格式、分辨率范围、对齐方式请参见Resize。

    接口使用流程请参考缩放。

    函数原型

    resize(inputImage: Image, resize: Size, interpolation: interpolation)

    输入参数说明

    参数名 类型 说明
    inputImage Image类 输入缩放前的Image类。
    resize Size类 输入图像缩放的宽高。
    interpolation interpolation参数枚举类 输入图像的缩放方式，默认为HUAWEI_HIGH_ORDER_FILTER。

    返回参数说明

    返回缩放后的Image类。

    抛异常接口

    缩放失败，抛出Runtime异常。

    VdecCallBacker

    类说明

    视频解码绑定回调函数类，用于绑定用户自定义的回调函数。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    回调函数格式

    函数功能

    回调函数用于接收VideoDecoder解码后的数据（如Image数据、frameId等）并在回调函数内实现自定义处理功能。

    用户如需实现自定义处理功能，建议进行简单的操作，如数据保存、列表写入（append），降低函数处理耗时，防止解码线程阻塞，导致视频解码速度变慢。

    函数原型

    def callback_func(decodedImage: Image, channelId: int, frameId: int) -> None

    输入参数说明

    callback_func为函数名称，用户可自定义，与registerVdecCallBack注册的函数名一致即可。

    参数名 类型 说明
    decodedImage Image类 解码后输出的图像类。
    channelId int 视频流索引，在VideoDecoder类初始化设置。
    frameId int 视频帧索引，由VideoDecoder类的decode函数来设置。

    [!NOTICE] 在回调函数中抛异常会触发C++侧抛出异常，引起程序coredump，建议在回调中捕获异常并处理。

    VdecCallBacker

    函数功能

    VdecCallBacker的构造函数。

    函数原型

    VdecCallBacker()

    返回参数说明

    VdecCallBacker对象。

    registerVdecCallBack

    函数功能

    将用户自定义的回调函数注册，以便解码后在回调函数中实现自定义操作。

    函数原型

    registerVdecCallBack(callback_func: Callable)

    输入参数说明

    参数名 类型 说明
    callback_func Python定义的函数名 需传入按指定格式定义的函数，否则将抛出异常。

    抛异常接口

    未按指定格式传入定义的回调函数，将抛出TypeError异常或Runtime异常。

    VideoDecoder

    类说明

    视频解码类，用于提供视频解码接口。

    接口使用流程请参考视频解码。

    • 为确保资源正确回收，建议在函数或类的成员方法中定义和运行VideoDecoder。若在全局作用域中定义VideoDecoder，则需要在程序结束时使用del函数删除构造的VideoDecoder对象。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    decode

    函数功能

    VideoDecoder的视频解码接口。

    函数原型

    decode(inputData: buffer, frameId: int)

    输入参数说明

    参数名 类型 说明
    inputData 二进制数据类型 传入视频帧二进制数据。
    frameId int 输入解码前视频帧的帧ID。

    返回参数说明

    无。（默认解码方式为非实时出帧，解码过程中存在缓存帧，Vdec需要在收到码流中的多帧数据后，才开始输出解码结果。）

    抛异常接口

    解码失败，抛出Runtime异常。

    VideoDecoder

    函数功能

    VideoDecoder类的构造函数。

    若因内存不足，pyVdecCallBacker未注册回调函数，或无法识别芯片等构造失败的场景会抛出“std::runtime_error”异常。

    函数原型

    VideoDecoder(pyVdecConfig: VideoDecodeConfig, pyVdecCallBacker: VdecCallBacker, deviceId: int, channelId: int)

    输入参数说明

    参数名 类型 说明
    pyVdecConfig VideoDecodeConfig类 视频解码的参数。
    pyVdecCallBacker VdecCallBacker类 绑定回调函数的VdecCallBacker类。（须先注册回调函数，否则构造VideoDecoder会抛出异常。）
    deviceId int 视频解码器部署的芯片，默认为0号芯片。取值范围：[0, 识别到的芯片个数 - 1]。
    channelId int 视频解码器的视频流索引。Atlas 200I/500 A2 推理产品：取值范围：[0, 127]。若存在重复构造相同channelId的场景，则会构造失败。Atlas 推理系列产品：取值范围：[0, 255]。若存在重复构造相同channelId的场景，则会进行自动调整channelId。

    返回参数说明

    VideoDecoder对象。

    VencCallBacker

    类说明

    视频编码绑定回调函数类，用于绑定用户自定义的回调函数。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    回调函数格式

    说明

    回调函数用于接收VideoEncoder编码后的数据（如视频帧数据、ByteSize、frameId等）并在回调函数内实现自定义处理功能。

    用户如需实现自定义处理功能，建议进行简单的操作，如数据保存、列表写入（append），降低函数处理耗时，防止编码线程阻塞，导致视频编码速度变慢。

    函数原型

    def callback_func(pyBytes: bytes, outDataSize: int, channelId: int, frameId: int) -> None

    输入参数说明

    callback_func为函数名称，用户可自定义，与registerVencCallBack注册的函数名一致即可。

    参数名 类型 说明
    pyBytes bytes 编码后输出视频帧字节数据。
    outDataSize int 编码后输出视频帧数据的内存大小。
    channelId int 视频流索引，在VideoEncoder类初始化设置。
    frameId int 视频帧索引，由VideoEncoder类的encode函数来设置。

    [!NOTICE] 在回调函数中抛异常会触发C++侧抛出异常，引起程序coredump，建议在回调中捕获异常并处理。

    VencCallBacker

    函数功能

    VencCallBacker的构造函数。

    函数原型

    VencCallBacker()

    返回参数说明

    VencCallBacker对象。

    registerVencCallBack

    函数功能

    将用户自定义的回调函数注册，以便编码后在回调函数中实现自定义操作。

    函数原型

    registerVencCallBack(callback_func: Callable)

    输入参数说明

    参数名 类型 说明
    callback_func Python定义的函数名 需传入按指定格式定义的函数，否则将抛出异常。

    抛异常接口

    未按指定格式传入定义的回调函数，将抛出TypeError异常或Runtime异常。

    VideoEncoder

    类说明

    VideoEncoder类，作为视频编码类，主要开放视频编码接口。

    接口使用流程请参考视频编码。

    • 为确保资源正确回收，建议在函数或类的成员方法中定义和运行VideoEncoder。若在全局作用域中定义VideoEncoder，则需要在程序结束时使用del函数删除构造的VideoEncoder对象。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    Note

    • VideoEncoder类涉及申请Device侧资源，与mx_deinit的作用域冲突，因此，其作用域不能大于或等于mx_deinit的作用域。
    • 编码器运行时可能会因为送帧频率过快、大于芯片处理速度等原因，导致某一帧编码失败。建议用户合理控制调用Encode接口的频率。如，当编码帧率为30fps时，调用Encode接口的间隔可以控制在33ms。
    • 当某一帧编码失败时，编码器会继续处理后续帧数据。用户可以通过回调函数中的帧ID等信息感知到该帧编码结果未获取。

    encode

    函数功能

    VideoEncoder的视频编码接口。

    函数原型

    encode(inputImage: Image, frameId: int)

    输入参数说明

    参数名 类型 说明
    inputImage Image类 输入编码前的Image类。
    frameId int 输入视频帧索引。

    抛异常接口

    编码失败，抛出Runtime异常。

    VideoEncoder

    函数功能

    VideoEncoder类的构造函数。

    若因内存不足，pyVencCallBacker未注册回调函数，或无法识别芯片等构造失败的场景会抛出“std::runtime_error”异常。

    函数原型

    VideoEncoder(pyVencConfig: VideoEncodeConfig, pyVencCallBacker: VencCallBacker, deviceId: int, channelId: int)

    输入参数说明

    参数名 类型 说明
    pyVencConfig VideoEncodeConfig类 视频编码的参数。结构体的参数说明请参见VideoEncodeConfig类。
    pyVencCallBacker VencCallBacker类 绑定回调函数的VencCallBacker类。（须先注册回调函数，否则构造VideoEncoder会抛出异常。）
    deviceId int 视频编码器部署的芯片，默认为0号芯片。取值范围：[0, 识别到的芯片个数 - 1]。
    channelId int 视频编码器的视频流索引。默认值为0。
  • Atlas 200I/500 A2 推理产品：只能实例化一个VideoEncoder，因此用户无需设置channelId。
  • Atlas 推理系列产品：取值范围：[0, 127]。
    		•

    返回参数说明

    VideoEncoder对象。

    DeviceMemory

    类说明

    从Device侧申请内存，获取内存指针地址的值。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    DeviceMemory

    函数功能

    从Device侧申请内存。

    函数原型

    DeviceMemory(size: int)

    输入参数说明

    参数名 类型 说明
    size int 申请内存的大小，单位Byte。

    返回参数说明

    DeviceMemory对象。

    get_data

    函数功能

    获取对象中内存指针的值。

    函数原型

    get_data()

    返回参数说明

    返回值 类型 说明
    Output int 返回对象内存指针中的值。

    dvpp

    模块说明

    dvpp模块预计于2025年12月退出，建议使用ImageProcessor类。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    read_image

    函数功能

    解码读取图片。

    输入输出格式及对齐方式请参见decode(inputPath, decodeFormat)。

    该接口预计2025年12月正式删除，请使用ImageProcessor类的图片解码decode接口。

    函数原型

    read_image(inputPath: str, deviceId: int, decodeFormat: image_format)

    输入参数说明

    参数名 类型 说明
    inputPath str 图片路径。
    deviceId int Device设备的ID号。
    decodeFormat image_format枚举类 输入图片的解码格式。

    返回参数说明

    Image对象。

    抛异常接口

    创建ImageProcessor失败、图片解码失败，抛出Runtime异常。

    resize

    函数功能

    图像缩放。输入输出范围及对齐方式请参见resize(inputImage, resize, interpolation)。

    该接口预计2025年12月正式删除，请使用ImageProcessor类的图像缩放resize接口。

    函数原型

    resize(inputImage: Image, resize: Size, interpolation: interpolation)

    输入参数说明

    参数名 类型 说明
    inputImage Image类 输入缩放前的Image类。
    resize Size类 输入图像缩放的宽高。
    interpolation interpolation参数枚举类 输入图像的缩放方式，默认为HUAWEI_HIGH_ORDER_FILTER 。

    返回参数说明

    Image对象。

    抛异常接口

    创建ImageProcessor失败、图片缩放失败，抛出Runtime异常。

    TensorOperations

    总体说明

    本章节作为张量处理接口的主目录，主要开放色域转换、裁剪、张量类型转换等接口。

    支持的型号

    接口的硬件支持情况如表1所示，标识的含义如下：

    • √：支持
    • x：不支持

    表 1 接口的硬件支持情况

    接口 Atlas 200I/500 A2 推理产品 Atlas 推理系列产品 Atlas 800I A2推理产品
    clip √ √ x
    convert_to √ √ x
    cvt_color √ √ √
    transpose_operator √ √ x
    divide √ √ x
    multiply √ √ x
    subtract √ √ x
    add √ √ x
    min_operator √ √ x
    max_operator √ √ x

    clip

    函数功能

    图像处理类，Tensor类的张量裁剪接口，用于将张量中的元素限制在给定的最小值和最大值之间（小于最小值的元素将会被替换为最小值、大于最大值的元素将会被替换为最大值）。

    当前支持Atlas 推理系列产品和Atlas 200I/500 A2 推理产品。

    • 接口中的输入输出Tensor必须在Device侧。
    • 输入参数对应Tensor的形状（Shape）不超过4维。

    函数原型

    clip(inputTensor: Tensor, minVal: float, maxVal: float)

    参数说明

    参数名 输入/输出 说明
    inputTensor 输入 Tensor类，支持dtype.float16、dtype.float32、dtype.uint8类型输入。
    minVal 输入 float类型，张量中裁剪后的最小值，小于最小值的元素将会被替换为最小值。“minVal”需小于或等于“maxVal”。
    maxVal 输入 float类型，张量中裁剪后的最大值，大于最大值的元素将会被替换为最大值。“maxVal”需大于或等于“minVal”。

    返回参数说明

    返回裁剪后的Tensor类数据。

    convert_to

    函数功能

    将Tensor的值转换为指定类型，支持dtype.float32、dtype.float16、dtype.int8、dtype.int32、dtype.uint8、dtype.int16、dtype.uint16、dtype.uint32、dtype.int64、dtype.uint64、dtype.double、dtype.bool类型的转换。

    当前支持Atlas 推理系列产品和Atlas 200I/500 A2 推理产品。

    • 接口中的输入输出Tensor必须在Device侧。

    函数原型

    convert_to(inputTensor: Tensor, dataType: dtype)

    参数说明

    参数名 输入/输出 说明
    inputTensor 输入 Tensor类，输入张量。
    dataType 输入 dtype类，指定转换的类型。

    返回参数说明

    返回类型转换后的Tensor类数据。

    cvt_color

    函数功能

    将Tensor的图像色域类型转换为指定的色域类型，支持以下类型间的转换。

    若设置“keepMargin”为“true”，输出宽度自动与16对齐。默认值为“false”，不保留Tensor中无效的边界区域。各产品支持的色域转换类型如表1 色域转换类型所示，标识的含义如下：

    • √：支持

    • x：不支持

      表 1 色域转换类型

    色域转换类型 Atlas 200I/500 A2 推理产品 Atlas 推理系列产品 Atlas 800I A2推理产品
    YUVSP420（nv12）转YUV400（GRAY） √ √ √
    YVUSP420（nv21）转YUV400（GRAY） x √ √
    YUVSP420（nv12）转RGB x √ √
    YUVSP420（nv12）转BGR x √ √
    YVUSP420（nv21）转RGB x √ √
    YVUSP420（nv21）转BGR x √ √
    RGB转YUVSP420（nv12） x √ √
    RGB转YVUSP420（nv21） x √ √
    BGR转YUVSP420（nv12） x √ √
    BGR转YVUSP420（nv21） x √ √
    RGB转YUV400（GRAY） x √ √
    BGR转YUV400（GRAY） x √ √
    BGR转RGB x √ √
    RGB转BGR x √ √
    RGB转RGBA x √ √
    RGBA转YUV400（GRAY） x √ √
    RGBA转RGB x √ √
    GRAY转RGB x √ x
    RGB转mRGBA x √ x

    Note

    RGBA转mRGBA需要依赖CANN 8.0.RC1或CANN 8.0.RC1以后的版本。

    函数原型

    cvt_color(inputTensor: Tensor, cvtColorMode: cvt_color_mode, keepMargin = False)

    参数说明

    参数名 输入/输出 说明
    inputTensor 输入 Tensor类，输入张量，不可为空，需在Device侧分配内存，数据类型为dtype.uint8。
  • 形状为 {高，宽，通道数} 的张量，通道数需要与输入格式一致。RGBA转mRGBA时只支持通道数为4。

    • 若inputTensor色域类型为base.yuv_400或base.nv12，设置输入张量形状时，高为图片显示高度的1.5倍。张量的高需要为3的倍数，宽为16的倍数，通道为1。
  • 输入张量宽度范围为[10, 4096]，高度范围为[6, 4096]，若输入或输出张量格式包含YUV400、YUVSP420、YVUSP420、GRAY时，宽度范围为[18, 4096]。
  • 如果是灰度图，支持形状为{高*宽}的张量。
    		•
    cvtColorMode 输入 枚举类值，对应色域转换的原始类型和目标类型。若**“cvtColorMode”**色域类型为“base.color_bgr2yuvsp420”、“base.color_rgb2yuvsp420”、“base.color_rgb2yvusp420”或base.color_bgr2yvusp420：
  • 建议输入的RGB Tensor宽高为偶数，否则输出图片的边缘可能存在异常数据。
  • 输出张量的高为输入张量高的1.5倍。例如，输入高为4096，输出的高则为6144，超过部分DVPP接口的限制，使用时需要注意是否满足后续业务需求。
    		•
    keepMargin 输入 输出的张量中是否保留Tensor中无效的边界区域，默认为False，不保留Tensor中无效的边界区域。若设置“keepMargin”为“true”，输出宽度自动与16对齐，保留无效区域。
    当cvtColorMode=base.color_gray2rgb或cvtColorMode=base.color_rgba2mrgba时，该参数无效。

    返回参数说明

    返回色域转换后的Tensor类数据。

    transpose_operator

    函数功能

    可通过指定的一组轴维度（axes），对输入的Tensor数据进行转置处理，如未指定具体轴维度，则默认对Tensor数据进行反序转置。

    功能仅支持在Device侧的Tensor数据。

    • 输入参数对应Tensor的形状（Shape）不超过4维。

    函数原型

    transpose_operator(input: Tensor, axes: List[int])

    输入参数说明

    参数名 类型 说明
    input Tensor类 待转置Tensor类。维度支持2维、3维、4维，数据类型支持base.dtype.float32、base.dtype.float16、base.dtype.uint8，具体请参见Tensor类的属性列表。
    axes List[int] 转置选项，长度必须与输入Tensor的维度一致。如传入空列表，则按照反序转置进行处理。若不为空列表则axes中的元素必须包含[0, size-1]区间中的数且每个数只能出现一次，其中size为输入Tensor的维度。

    返回参数说明

    返回转置后的Tensor类数据。

    divide

    函数功能

    图像处理类算法，张量除法divide，支持dtype.float16、dtype.float32、dtype.uint8。

    当前支持Atlas 推理系列产品和Atlas 200I/500 A2 推理产品。

    • 接口中的输入输出Tensor必须在Device侧。

    • 输入参数对应Tensor的形状（Shape）相等且不超过4维。

    • scale参数仅支持在Atlas 推理系列产品下传入。支持不同输入数据类型，输出数据类型与精度高的输入Tensor保持一致。

    • 请注意处理数据类型越界问题。

    函数原型

    divide(inputTensor1: Tensor, inputTensor2: Tensor, scale)

    输入参数说明

    参数名 类型 说明
    inputTensor1 Tensor类 被除数，输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。
    inputTensor2 Tensor类 除数，输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。
    scale float 可选参数，表示被除数被缩放的倍数（该参数仅支持在Atlas 推理系列产品下使用）。

    返回参数说明

    返回相除后的Tensor类数据。

    multiply

    函数功能

    图像处理类算法，张量乘法multiply，支持dtype.float16、dtype.float32、dtype.uint8。

    当前支持Atlas 推理系列产品和Atlas 200I/500 A2 推理产品。

    • 接口中的输入输出Tensor必须在Device侧。
    • 输入参数对应Tensor的形状（Shape）相等且不超过4维。
    • 当不传入scale时，输入参数的各数据类型需保持一致；若传入，支持不同输入数据类型，输出数据类型与精度高的输入Tensor保持一致。
    • 请注意处理数据类型越界问题。

    函数原型

    multiply(inputTensor1: Tensor, inputTensor2: Tensor, scale)

    输入参数说明

    参数名 类型 说明
    inputTensor1 Tensor类 乘数，输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。
    inputTensor2 Tensor类 乘数，输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。
    scale float 可选参数，表示结果被缩放的倍数。

    返回参数说明

    返回相乘后的Tensor类数据。

    subtract

    函数功能

    图像处理类算法，张量减法subtract，支持dtype.float16、dtype.float32、dtype.uint8。

    当前支持Atlas 推理系列产品和Atlas 200I/500 A2 推理产品。

    • 接口中的输入输出Tensor必须在Device侧。
    • 输入参数对应Tensor的形状（Shape）相等且不超过4维。
    • 请注意处理数据类型越界问题。

    函数原型

    subtract(inputTensor1: Tensor, inputTensor2: Tensor)

    输入参数说明

    参数名 类型 说明
    inputTensor1 Tensor类 被减数，输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。
    inputTensor2 Tensor类 减数，输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。

    返回参数说明

    返回相减后的Tensor类数据。

    add

    函数功能

    图像处理类算法，张量加法add，支持dtype.float16、dtype.float32、dtype.uint8。

    当前支持Atlas 推理系列产品和Atlas 200I/500 A2 推理产品。

    • 接口中的输入输出Tensor必须在Device侧。
    • 输入参数对应Tensor的形状（Shape）相等且不超过4维。
    • 请注意处理数据类型越界问题。

    函数原型

    add(inputTensor1: Tensor, inputTensor2: Tensor)

    输入参数说明

    参数名 类型 说明
    inputTensor1 Tensor类 加数，输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。
    inputTensor2 Tensor类 加数，输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。

    返回参数说明

    返回相加后的Tensor类数据。

    min_operator

    函数功能

    图像处理类算法，张量取较小值计算min_operator，对两个输入Tensor按元素比较并取较小值，支持dtype.float16、dtype.float32、dtype.uint8类型。

    • 当前支持Atlas 推理系列产品和Atlas 200I/500 A2 推理产品。
    • 接口中的输入Tensor必须在Device侧。
    • 输入参数对应Tensor的类型和形状（Shape）一致且不超过4维。

    函数原型

    min_operator(inputTensor1: Tensor, inputTensor2: Tensor)

    输入参数说明

    参数名 类型 说明
    inputTensor1 Tensor类 输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。
    inputTensor2 Tensor类 输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。

    返回参数说明

    返回进行逐项取较小值后的Tensor类数据。

    max_operator

    函数功能

    图像处理类算法，张量取较大值计算max_operator，对两个输入Tensor按元素比较并取较大值，支持dtype.float16、dtype.float32、dtype.uint8类型。

    • 当前支持Atlas 推理系列产品和Atlas 200I/500 A2 推理产品。
    • 接口中的输入Tensor必须在Device侧。
    • 输入参数对应Tensor的类型和形状（Shape）一致且形状不超过4维。

    函数原型

    max_operator(inputTensor1: Tensor, inputTensor2: Tensor)

    输入参数说明

    参数名 类型 说明
    inputTensor1 Tensor类 输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。
    inputTensor2 Tensor类 输入张量，支持dtype.float16、dtype.float32、dtype.uint8类型输入。

    返回参数说明

    返回进行逐项取较大值后的Tensor类数据。

    batch_concat

    函数功能

    将多个Tensor进行组batch，按照第0维组装，内存连续。

    函数原型

    batch_concat(inputs: List)

    输入参数说明

    参数名 类型 说明
    inputs List[base.Tensor] Tensor列表。

    返回参数说明

    Tensor对象。

    抛异常接口

    传入Tensor异常、组Tensor后输出的Tensor异常，抛出Runtime异常。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    bytes_to_ptr

    函数功能

    将二进制数据转换成指针地址值。

    函数原型

    bytes_to_ptr(data: buffer)

    输入参数说明

    参数名 类型 说明
    data 二进制数据类型 传二进制数据。

    返回参数说明

    返回指针地址值。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    image

    函数功能

    解码读取图片。

    输入输出格式及对齐方式请参见decode(inputPath, decodeFormat)。

    函数原型

    image(inputPath: str, deviceId: int, decodeFormat: image_format)

    输入参数说明

    参数名 类型 说明
    inputPath str 图片路径。
    deviceId int Device设备的ID号。
    decodeFormat image_format枚举类 输入图片的解码格式。

    返回参数说明

    Image对象。

    抛异常接口

    创建ImageProcessor失败、图片解码失败，抛出Runtime异常。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    resize_info

    函数功能

    设置缩放信息。

    函数原型

    resize_info(image: Image, resize_height: int, resize_width: int, resize_type: ResizeType)

    输入参数说明

    参数名 类型 说明
    image Image对象 图像信息。
    resize_height int 缩放高度。
    resize_width int 缩放宽度。
    resize_type ResizeType 缩放类型。

    返回参数说明

    ResizedImageInfo对象。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    transpose

    函数功能

    可通过指定的一组轴维度（axes），对输入的Tensor数据进行转置处理，如未指定具体轴维度，则默认对Tensor数据进行反序转置。

    功能仅支持在Host侧执行操作，如需处理Device侧Tensor数据，请先通过to_host接口，将Device侧数据转移到Host侧，再进行转置。

    函数原型

    transpose(input: Tensor, axes: List)

    输入参数说明

    参数名 类型 说明
    input Tensor类 待转置Tensor类。维度支持2维、3维、4维，数据类型支持base.dtype.float32、base.dtype.float16、base.dtype.uint8，具体请参见Tensor类的属性列表。
    axes List[int] 转置选项，默认值为空。如果未指定具体axes，则默认生成反序axes对input中的数据进行反序转置。例如：三维张量默认生成反序axes为{2, 1, 0} 。

    返回参数说明

    返回转置后的Tensor类数据。

    支持的型号

    Atlas 200I/500 A2 推理产品

    Atlas 推理系列产品

    tensor_to_image

    函数功能

    将Host侧Tensor类转换为Host侧Image类，或将Device侧Tensor类转换为DVPP侧Image类。

    当前接口仅能够在Atlas 推理系列产品和Atlas 800I A2推理产品环境上调用。

    在转换过程中，会对Image的宽进行16向上对齐、对Image的高进行2向上对齐，转换后的Image类对象将存在补边区域。

    转换后的Image类可通过类对象属性width和height查看补边后的宽、高，通过类对象属性original_width和original_height查看图片原始宽、高。

    例如：

    • Tensor类对象对应的图片宽、高为500、499时，转换得到的Image类对象在补边后，通过Image类对象属性original_width和original_height可获得原始宽、高分别为500、499，通过Image类对象属性width和height可获得对齐后的宽、高分别为512、500。
    • Tensor类对象对应的图片宽、高为512、500时，转换得到的Image类对象不需要补边，即转换后的Image类对象的原始宽、高分别为512、500，Image类对象的对齐后的宽、高分别为512、500。

    函数原型

    tensor_to_image(tensor: Tensor, imageFormat: image_format)

    参数说明

    参数名 类型 说明
    tensor Tensor类 Tensor类，输入张量。输入需满足以下要求。
  • 元素类型需为uint8类型。
  • Tensor的维度需为2（YUV400格式时）、3、4。
  • Tensor的宽、高、通道数需与imageFormat相匹配。
    		•
    imageFormat image_format枚举类 指定图片的格式，需与inputTensor数据所对应的图片格式相匹配。

    返回参数说明

    返回对应的Image对象。