Python API#

nvImageCodec Python API 参考

这是 NVIDIA® nvImageCodec 库的 Python API 参考。

Backend#

class nvidia.nvimgcodec.Backend#
__init__(*args, **kwargs)#

重载函数。

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Backend) -> None

默认构造函数

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Backend, backend_kind: nvidia.nvimgcodec.nvimgcodec_impl.BackendKind, load_hint: float = 1.0, load_hint_policy: nvidia.nvimgcodec.nvimgcodec_impl.LoadHintPolicy = <LoadHintPolicy.FIXED: 2>) -> None

带参数的构造函数

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Backend, backend_kind: nvidia.nvimgcodec.nvimgcodec_impl.BackendKind, backend_params: nvidia.nvimgcodec.nvimgcodec_impl.BackendParams) -> None

带后端参数的构造函数

property backend_kind#

后端类型 (例如 GPU_ONLY 或 CPU_ONLY)。

property backend_params#

后端参数。

property load_hint#

将由此后端选取的批处理样本的比例。剩余样本将由下一个较低优先级的后端选取。

property load_hint_policy#

定义如何使用加载提示

BackendKind#

class nvidia.nvimgcodec.BackendKind#

成员

CPU_ONLY

GPU_ONLY

HYBRID_CPU_GPU

HW_GPU_ONLY

LoadHintPolicy#

class nvidia.nvimgcodec.LoadHintPolicy#

成员

IGNORE

FIXED

ADAPTIVE_MINIMIZE_IDLE_TIME

BackendParams#

class nvidia.nvimgcodec.BackendParams#
__init__(*args, **kwargs)#

重载函数。

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.BackendParams) -> None

默认构造函数

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.BackendParams, load_hint: float = 1.0, load_hint_policy: nvidia.nvimgcodec.nvimgcodec_impl.LoadHintPolicy = <LoadHintPolicy.FIXED: 2>) -> None

带加载参数的构造函数

property load_hint#

将由此后端选取的批处理样本的比例。剩余样本将由下一个较低优先级的后端选取。这只是一个提示，因此特定的编解码器可以忽略此值

property load_hint_policy#

定义如何使用加载提示

ChromaSubsampling#

class nvidia.nvimgcodec.ChromaSubsampling#

成员

CSS_444

CSS_422

CSS_420

CSS_440

CSS_411

CSS_410

CSS_GRAY

CSS_410V

DecodeParams#

class nvidia.nvimgcodec.DecodeParams#
__init__(*args, **kwargs)#

重载函数。

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams) -> None

默认构造函数

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams, apply_exif_orientation: bool = True, color_spec: nvidia.nvimgcodec.nvimgcodec_impl.ColorSpec = <ColorSpec.RGB: 1>, allow_any_depth: bool = False) -> None

带有 apply_exif_orientation、color_spec 参数和 allow_any_depth 的构造函数

property allow_any_depth#

允许任何原生位深。如果未启用，动态范围将缩放到 uint8。

property apply_exif_orientation#

如果可用，则应用 EXIF 方向

property color_spec#

颜色规范

Decoder#

class nvidia.nvimgcodec.Decoder#
__init__(*args, **kwargs)#

重载函数。

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Decoder, device_id: int = -1, max_num_cpu_threads: int = 0, backends: Optional[list[nvidia.nvimgcodec.nvimgcodec_impl.Backend]] = None, options: str = ‘:fancy_upsampling=0’) -> None

    初始化解码器。

    参数

    device_id：在其上执行解码的设备 ID。

    max_num_cpu_threads：默认执行器中的最大 CPU 线程数（0 表示默认值等于 CPU 核心数）

    backends：允许的后端列表。如果为空，则允许使用所有后端和默认参数。

    options：解码器特定的选项，例如：“nvjpeg:fancy_upsampling=1”

  2. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Decoder, device_id: int = -1, max_num_cpu_threads: int = 0, backend_kinds: Optional[list[nvidia.nvimgcodec.nvimgcodec_impl.BackendKind]] = None, options: str = ‘:fancy_upsampling=0’) -> None

    初始化解码器。

    参数

    device_id：在其上执行解码的设备 ID。

    max_num_cpu_threads：默认执行器中的最大 CPU 线程数（0 表示默认值等于 CPU 核心数）

    backend_kinds：允许的后端类型列表。如果为空或 None，则允许使用所有后端和默认参数。

    options：解码器特定的选项，例如：“nvjpeg:fancy_upsampling=1”

decode(*args, **kwargs)#

重载函数。

  1. decode(self: nvidia.nvimgcodec.nvimgcodec_impl.Decoder, src: nvidia.nvimgcodec.nvimgcodec_impl.DecodeSource, params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams] = None, cuda_stream: int = 0) -> object

    执行从 DecodeSource 句柄（代码流句柄和一个可选的感兴趣区域）解码数据。

    参数

    src：解码源对象。

    params：解码参数。

    cuda_stream：一个可选的 cudaStream_t，表示为 Python 整数，必须在其上进行同步。

    返回值

    nvimgcodec.Image；如果由于任何原因无法解码图像，则返回 None。

  2. decode(self: nvidia.nvimgcodec.nvimgcodec_impl.Decoder, srcs: list[nvidia.nvimgcodec.nvimgcodec_impl.DecodeSource], params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams] = None, cuda_stream: int = 0) -> list[object]

    执行从一批 DecodeSource 句柄（代码流句柄和一个可选的感兴趣区域）解码。

    参数

    srcs：DecodeSource 对象列表

    params：解码参数。

    cuda_stream：一个可选的 cudaStream_t，表示为 Python 整数，必须在其上进行同步。

    返回值

    解码后的 nvimgcodec.Image 列表

read(*args, **kwargs)#

重载函数。

  1. read(self: nvidia.nvimgcodec.nvimgcodec_impl.Decoder, path: nvidia.nvimgcodec.nvimgcodec_impl.DecodeSource, params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams] = None, cuda_stream: int = 0) -> object

    执行从文件名解码。

    参数

    path：要解码的文件路径。

    params：解码参数。

    cuda_stream：一个可选的 cudaStream_t，表示为 Python 整数，必须在其上进行同步。

    返回值

    nvimgcodec.Image；如果由于任何原因无法解码图像，则返回 None。

  2. read(self: nvidia.nvimgcodec.nvimgcodec_impl.Decoder, paths: list[nvidia.nvimgcodec.nvimgcodec_impl.DecodeSource], params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams] = None, cuda_stream: int = 0) -> list[object]

    执行从一批文件路径解码。

    参数

    path：要解码的文件路径列表。

    params：解码参数。

    cuda_stream：一个可选的 cudaStream_t，表示为 Python 整数，必须在其上进行同步。

    返回值

    解码后的 nvimgcodec.Image 列表

JpegEncodeParams#

class nvidia.nvimgcodec.JpegEncodeParams#
__init__(*args, **kwargs)#

重载函数。

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.JpegEncodeParams) -> None

默认构造函数

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.JpegEncodeParams, progressive: bool = False, optimized_huffman: bool = False) -> None

带有 progressive、optimized_huffman 参数的构造函数

property optimized_huffman#

使用带有优化 Huffman 的 Jpeg 编码（默认为 False）

property progressive#

使用 Jpeg 渐进式编码（默认为 False）

Jpeg2kEncodeParams#

class nvidia.nvimgcodec.Jpeg2kEncodeParams#
__init__(*args, **kwargs)#

重载函数。

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Jpeg2kEncodeParams) -> None

默认构造函数

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Jpeg2kEncodeParams, reversible: bool = False, code_block_size: tuple[int, int] = (64, 64), num_resolutions: int = 5, bitstream_type: nvidia.nvimgcodec.nvimgcodec_impl.Jpeg2kBitstreamType = <Jpeg2kBitstreamType.JP2: 1>, prog_order: nvidia.nvimgcodec.nvimgcodec_impl.Jpeg2kProgOrder = <Jpeg2kProgOrder.RPCL: 2>) -> None

带有 reversible、code_block_size、num_resolutions、bitstream_type、prog_order 参数的构造函数

property bitstream_type#

Jpeg 2000 比特流类型（默认为 JP2）

property code_block_size#

Jpeg 2000 代码块宽度和高度（默认为 64x64）

property num_resolutions#

Jpeg 2000 分辨率数 - 分解级别（默认为 5）

property prog_order#

Jpeg 2000 渐进顺序（默认为 RPCL）

property reversible#

使用可逆 Jpeg 2000 变换（默认为 False）

EncodeParams#

class nvidia.nvimgcodec.EncodeParams#
__init__(*args, **kwargs)#

重载函数。

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.EncodeParams) -> None

默认构造函数

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.EncodeParams, quality: float = 95, target_psnr: float = 50, color_spec: nvidia.nvimgcodec.nvimgcodec_impl.ColorSpec = <ColorSpec.UNCHANGED: 0>, chroma_subsampling: nvidia.nvimgcodec.nvimgcodec_impl.ChromaSubsampling = <ChromaSubsampling.CSS_444: 0>, jpeg_encode_params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.JpegEncodeParams] = None, jpeg2k_encode_params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.Jpeg2kEncodeParams] = None) -> None

带有 quality、target_psnr、color_spec、chroma_subsampling 等参数的构造函数

property chroma_subsampling#

色度二次采样（默认为 ChromaSubsampling.CSS_444）

property color_spec#

输出颜色规范（默认为 ColorSpec.UNCHANGED）

property jpeg2k_params#

Jpeg2000 编码参数

property jpeg_params#

Jpeg 编码参数

property quality#

质量值 0-100（默认为 95），对于 WebP，大于 100 的值表示无损。

property target_psnr#

目标 psnr（默认为 50）

Encoder#

class nvidia.nvimgcodec.Encoder#
__init__(*args, **kwargs)#

重载函数。

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Encoder, device_id: int = -1, max_num_cpu_threads: int = 0, backends: Optional[list[nvidia.nvimgcodec.nvimgcodec_impl.Backend]] = None, options: str = ‘’) -> None

    初始化编码器。

    参数

    device_id：在其上执行编码的设备 ID。

    max_num_cpu_threads：默认执行器中的最大 CPU 线程数（0 表示默认值等于 CPU 核心数）

    backends：允许的后端列表。如果为空，则允许使用所有后端和默认参数。

    options：编码器特定的选项。

  2. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Encoder, device_id: int = -1, max_num_cpu_threads: int = 0, backend_kinds: Optional[list[nvidia.nvimgcodec.nvimgcodec_impl.BackendKind]] = None, options: str = ‘:fancy_upsampling=0’) -> None

    初始化编码器。

    参数

    device_id：在其上执行编码的设备 ID。

    max_num_cpu_threads：默认执行器中的最大 CPU 线程数（0 表示默认值等于 CPU 核心数）

    backend_kinds：允许的后端类型列表。如果为空或 None，则允许使用所有后端和默认参数。

    options：编码器特定的选项。

encode(
self: nvidia.nvimgcodec.nvimgcodec_impl.Encoder,
image_s: object,
codec: str,
params: nvidia.nvimgcodec.nvimgcodec_impl.EncodeParams | None = None,
cuda_stream: int = 0,
) → object#

将图像编码到缓冲区。

参数:

  • image_s – 要编码的图像或图像列表

  • codec – 定义输出格式的字符串，例如“jpeg2k”。当它是文件扩展名时，必须包含前导句点，例如“.jp2”。

  • params – 编码参数。

  • cuda_stream – 一个可选的 cudaStream_t，表示为 Python 整数，必须在其上进行同步。

返回值:

包含压缩代码流的缓冲区或缓冲区列表。如果由于任何原因无法编码图像，则返回 None。

write(*args, **kwargs)#

重载函数。

  1. write(self: nvidia.nvimgcodec.nvimgcodec_impl.Encoder, file_name: str, image: object, codec: str = ‘’, params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.EncodeParams] = None, cuda_stream: int = 0) -> None

    将图像编码到文件。

    参数

    file_name：用于保存编码代码流的文件名。

    image：要编码的图像

    codec：定义输出格式的字符串，例如“jpeg2k”。当它是文件扩展名时，必须包含前导句点，例如“.jp2”。如果未指定编解码器，则根据文件扩展名推断。如果没有扩展名，则默认选择“jpeg”。

    params：编码参数。

    cuda_stream：一个可选的 cudaStream_t，表示为 Python 整数，必须在其上进行同步。

    返回值

    无

  2. write(self: nvidia.nvimgcodec.nvimgcodec_impl.Encoder, file_names: list[str], images: list[object], codec: str = ‘’, params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.EncodeParams] = None, cuda_stream: int = 0) -> None

    将批量图像编码到文件。

    参数

    file_names：用于保存编码代码流的文件名列表。

    images：要编码的图像列表。

    codec：定义输出格式的字符串，例如“jpeg2k”。当它是文件扩展名时，必须包含前导句点，例如“.jp2”。如果未指定编解码器，则根据文件扩展名推断。如果没有扩展名，则默认选择“jpeg”。（可选）

    params：编码参数。

    cuda_stream：一个可选的 cudaStream_t，表示为 Python 整数，必须在其上进行同步。

    返回值

    包含压缩代码流的缓冲区列表。

ImageBufferKind#

class nvidia.nvimgcodec.ImageBufferKind#

定义存储图像数据的缓冲区类型。

成员

STRIDED_DEVICE：GPU 可访问，平面采用倾斜线性布局。

STRIDED_HOST：主机可访问，平面采用倾斜线性布局。

Image#

class nvidia.nvimgcodec.Image#

包装像素缓冲区的类。它可以是解码后的像素或要编码的像素。

property __cuda_array_interface__#

与 Numba v0.39.0 或更高版本兼容的 CUDA 数组交换接口（有关详细信息，请参阅 CUDA 数组接口）

__dlpack__(
self: nvidia.nvimgcodec.nvimgcodec_impl.Image,
stream: object = None,
) → capsule#

将图像导出为 DLPack 张量

__dlpack_device__(
self: nvidia.nvimgcodec.nvimgcodec_impl.Image,
) → tuple#

获取与缓冲区关联的设备

property buffer_kind#

存储图像数据的缓冲区类型。

cpu(self: nvidia.nvimgcodec.nvimgcodec_impl.Image) → object#

返回此图像在 CPU 内存中的副本。如果此图像已在 CPU 内存中，则不执行复制，并返回原始对象。

返回值:

内容在 CPU 内存中的 Image 对象；如果无法完成复制，则返回 None。

cuda(
self: nvidia.nvimgcodec.nvimgcodec_impl.Image,
synchronize: bool = True,
) → object#

返回此图像在设备内存中的副本。如果此图像已在设备内存中，则不执行复制，并返回原始对象。

参数:

synchronize – 如果为 True（默认），则会阻塞并等待从主机到设备的复制完成；否则不执行同步，并且需要使用例如 __cuda_array_interface__ 提供的 cuda 流来完成进一步的同步。

返回值:

内容在设备内存中的 Image 对象；如果无法完成复制，则返回 None。

property dtype#
property height#
property ndim#
property precision#

数据类型中有效位的最大数量。值 0 表示精度等于数据类型位深度

property shape#
property strides#

轴的步长（以字节为单位）

to_dlpack(
self: nvidia.nvimgcodec.nvimgcodec_impl.Image,
cuda_stream: object = None,
) → capsule#

通过零拷贝转换将图像导出为 DLPack 张量。

参数:

cuda_stream – 一个可选的 cudaStream_t，表示为 Python 整数，必须在新创建的 Image 中在其上进行同步。

返回值:

封装在 PyCapsule 对象中的 DLPack 张量。

property width#

Jpeg2kBitstreamType#

class nvidia.nvimgcodec.Jpeg2kBitstreamType#

成员

J2K

JP2

Jpeg2kProgOrder#

class nvidia.nvimgcodec.Jpeg2kProgOrder#

成员

LRCP

RLCP

RPCL

PCRL

CPRL

ColorSpec#

class nvidia.nvimgcodec.ColorSpec#

成员

UNCHANGED

YCC

RGB

GRAY

as_image#

nvidia.nvimgcodec.as_image(
source: object,
cuda_stream: int = 0,
) → nvidia.nvimgcodec.nvimgcodec_impl.Image#

将外部缓冲区包装为图像，并将缓冲区生命周期绑定到图像

参数:

  • source – 输入 DLPack 张量，封装在 PyCapsule 对象中，或其他具有 __cuda_array_interface__、__array_interface__ 或 __dlpack__ 和 __dlpack_device__ 方法的对象中。

  • cuda_stream – 一个可选的 cudaStream_t，表示为 Python 整数，必须在新创建的 Image 中在其上进行同步。

返回值:

nvimgcodec.Image

as_images#

nvidia.nvimgcodec.as_images(sources: list[object], cuda_stream: int = 0) → list[object]#

将所有外部缓冲区包装为图像，并将缓冲区生命周期绑定到图像

参数:

  • sources – 输入 DLPack 张量列表，封装在 PyCapsule 对象中，或其他具有 __cuda_array_interface__、__array_interface__ 或 __dlpack__ 和 __dlpack_device__ 方法的对象中。

  • cuda_stream – 一个可选的 cudaStream_t，表示为 Python 整数，必须在新创建的 Image 中在其上进行同步。

返回值:

nvimgcodec.Image 列表

from_dlpack#

nvidia.nvimgcodec.from_dlpack(
source: object,
cuda_stream: int = 0,
) → nvidia.nvimgcodec.nvimgcodec_impl.Image#

从 DLPack 张量到图像的零拷贝转换。

参数:

  • source – 输入 DLPack 张量，封装在 PyCapsule 对象中，或其他具有 __dlpack__ 和 __dlpack_device__ 方法的（数组）对象中。

  • cuda_stream – 一个可选的 cudaStream_t，表示为 Python 整数，必须在新创建的 Image 中在其上进行同步。

返回值:

nvimgcodec.Image