Python API#

nvImageCodec Python API reference

This is the Python API reference for the NVIDIA® nvImageCodec library.

Backend#

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

Overloaded function.

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

Default constructor

  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

Constructor with parameters

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

Constructor with backend parameters

property backend_kind#

Backend kind (e.g. GPU_ONLY or CPU_ONLY).

property backend_params#

Backend parameters.

property load_hint#

Fraction of the batch samples that will be picked by this backend. The remaining samples will be picked by the next lower priority backend.

property load_hint_policy#

Defines how to use the load hint

BackendKind#

class nvidia.nvimgcodec.BackendKind#

Members:

CPU_ONLY

GPU_ONLY

HYBRID_CPU_GPU

HW_GPU_ONLY

LoadHintPolicy#

class nvidia.nvimgcodec.LoadHintPolicy#

Members:

IGNORE

FIXED

ADAPTIVE_MINIMIZE_IDLE_TIME

BackendParams#

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

Overloaded function.

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

Default constructor

  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

Constructor with load parameters

property load_hint#

Fraction of the batch samples that will be picked by this backend. The remaining samples will be picked by the next lower priority backend. This is just hint, so particular codecs can ignore this value

property load_hint_policy#

Defines how to use the load hint

ChromaSubsampling#

class nvidia.nvimgcodec.ChromaSubsampling#

Members:

CSS_444

CSS_422

CSS_420

CSS_440

CSS_411

CSS_410

CSS_GRAY

CSS_410V

DecodeParams#

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

Overloaded function.

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

Default constructor

  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

Constructor with apply_exif_orientation, color_spec parameters, and allow_any_depth

property allow_any_depth#

Allow any native bitdepth. If not enabled, the dynamic range is scaled to uint8.

property apply_exif_orientation#

Apply EXIF orientation if available

property color_spec#

Color specification

Decoder#

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

Overloaded function.

  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

    Initialize decoder.

    Args:

    device_id: Device id to execute decoding on.

    max_num_cpu_threads: Max number of CPU threads in default executor (0 means default value equal to number of cpu cores)

    backends: List of allowed backends. If empty, all backends are allowed with default parameters.

    options: Decoder specific options e.g.: “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

    Initialize decoder.

    Args:

    device_id: Device id to execute decoding on.

    max_num_cpu_threads: Max number of CPU threads in default executor (0 means default value equal to number of cpu cores)

    backend_kinds: List of allowed backend kinds. If empty or None, all backends are allowed with default parameters.

    options: Decoder specific options e.g.: “nvjpeg:fancy_upsampling=1”

decode(*args, **kwargs)#

Overloaded function.

  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

    Executes decoding of data from a DecodeSource handle (code stream handle and an optional region of interest).

    Args:

    src: decode source object.

    params: Decode parameters.

    cuda_stream: An optional cudaStream_t represented as a Python integer, upon which synchronization must take place.

    Returns:

    nvimgcodec.Image or None if the image cannot be decoded because of any reason.

  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]

    Executes decoding from a batch of DecodeSource handles (code stream handle and an optional region of interest).

    Args:

    srcs: List of DecodeSource objects

    params: Decode parameters.

    cuda_stream: An optional cudaStream_t represented as a Python integer, upon which synchronization must take place.

    Returns:

    List of decoded nvimgcodec.Image’s

read(*args, **kwargs)#

Overloaded function.

  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

    Executes decoding from a filename.

    Args:

    path: File path to decode.

    params: Decode parameters.

    cuda_stream: An optional cudaStream_t represented as a Python integer, upon which synchronization must take place.

    Returns:

    nvimgcodec.Image or None if the image cannot be decoded because of any reason.

  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]

    Executes decoding from a batch of file paths.

    Args:

    path: List of file paths to decode.

    params: Decode parameters.

    cuda_stream: An optional cudaStream_t represented as a Python integer, upon which synchronization must take place.

    Returns:

    List of decoded nvimgcodec.Image’s

JpegEncodeParams#

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

Overloaded function.

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

Default constructor

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

Constructor with progressive, optimized_huffman parameters

property optimized_huffman#

Use Jpeg encoding with optimized Huffman (default False)

property progressive#

Use Jpeg progressive encoding (default False)

Jpeg2kEncodeParams#

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

Overloaded function.

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

Default constructor

  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

Constructor with reversible, code_block_size, num_resolutions, bitstream_type, prog_order parameters

property bitstream_type#

Jpeg 2000 bitstream type (default JP2)

property code_block_size#

Jpeg 2000 code block width and height (default 64x64)

property num_resolutions#

Jpeg 2000 number of resolutions - decomposition levels (default 5)

property prog_order#

Jpeg 2000 progression order (default RPCL)

property reversible#

Use reversible Jpeg 2000 transform (default False)

EncodeParams#

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

Overloaded function.

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

Default constructor

  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

Constructor with quality, target_psnr, color_spec, chroma_subsampling etc. parameters

property chroma_subsampling#

Chroma subsampling (default ChromaSubsampling.CSS_444)

property color_spec#

Output color specification (default ColorSpec.UNCHANGED)

property jpeg2k_params#

Jpeg2000 encode parameters

property jpeg_params#

Jpeg encode parameters

property quality#

Quality value 0-100 (default 95), for WebP value greater than 100 means lossless.

property target_psnr#

Target psnr (default 50)

Encoder#

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

Overloaded function.

  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

    Initialize encoder.

    Args:

    device_id: Device id to execute encoding on.

    max_num_cpu_threads: Max number of CPU threads in default executor (0 means default value equal to number of cpu cores)

    backends: List of allowed backends. If empty, all backends are allowed with default parameters.

    options: Encoder specific 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

    Initialize encoder.

    Args:

    device_id: Device id to execute encoding on.

    max_num_cpu_threads: Max number of CPU threads in default executor (0 means default value equal to number of cpu cores)

    backend_kinds: List of allowed backend kinds. If empty or None, all backends are allowed with default parameters.

    options: Encoder specific 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#

Encode image(s) to buffer(s).

Parameters:

  • image_s – Image or list of images to encode

  • codec – String that defines the output format e.g.’jpeg2k’. When it is file extension it must include a leading period e.g. ‘.jp2’.

  • params – Encode parameters.

  • cuda_stream – An optional cudaStream_t represented as a Python integer, upon which synchronization must take place.

Returns:

Buffer or list of buffers with compressed code stream(s). None if the image(s) cannot be encoded because of any reason.

write(*args, **kwargs)#

Overloaded function.

  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

    Encode image to file.

    Args:

    file_name: File name to save encoded code stream.

    image: Image to encode

    codec: String that defines the output format e.g.’jpeg2k’. When it is file extension it must include a leading period e.g. ‘.jp2’. If codec is not specified, it is deducted based on file extension. If there is no extension by default ‘jpeg’ is choosen.

    params: Encode parameters.

    cuda_stream: An optional cudaStream_t represented as a Python integer, upon which synchronization must take place.

    Returns:

    None

  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

    Encode batch of images to files.

    Args:

    file_names: List of file names to save encoded code streams.

    images: List of images to encode.

    codec: String that defines the output format e.g.’jpeg2k’. When it is file extension it must include a leading period e.g. ‘.jp2’. If codec is not specified, it is deducted based on file extension. If there is no extension by default ‘jpeg’ is choosen. (optional)

    params: Encode parameters.

    cuda_stream: An optional cudaStream_t represented as a Python integer, upon which synchronization must take place.

    Returns:

    List of buffers with compressed code streams.

ImageBufferKind#

class nvidia.nvimgcodec.ImageBufferKind#

Defines buffer kind in which image data is stored.

Members:

STRIDED_DEVICE : GPU-accessible with planes in pitch-linear layout.

STRIDED_HOST : Host-accessible with planes in pitch-linear layout.

Image#

class nvidia.nvimgcodec.Image#

Class which wraps buffer with pixels. It can be decoded pixels or pixels to encode.

property __cuda_array_interface__#

The CUDA array interchange interface compatible with Numba v0.39.0 or later (see CUDA Array Interface for details)

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

Export the image as a DLPack tensor

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

Get the device associated with the buffer

property buffer_kind#

Buffer kind in which image data is stored.

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

Returns a copy of this image in CPU memory. If this image is already in CPU memory, than no copy is performed and the original object is returned.

Returns:

Image object with content in CPU memory or None if copy could not be done.

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

Returns a copy of this image in device memory. If this image is already in device memory, than no copy is performed and the original object is returned.

Parameters:

synchronize – If True (by default) it blocks and waits for copy from host to device to be finished, else not synchronization is executed and further synchronization needs to be done using cuda stream provided by e.g. __cuda_array_interface__.

Returns:

Image object with content in device memory or None if copy could not be done.

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

Maximum number of significant bits in data type. Value 0 means that precision is equal to data type bit depth

property shape#
property strides#

Strides of axes in bytes

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

Export the image with zero-copy conversion to a DLPack tensor.

Parameters:

cuda_stream – An optional cudaStream_t represented as a Python integer, upon which synchronization must take place in created Image.

Returns:

DLPack tensor which is encapsulated in a PyCapsule object.

property width#

Jpeg2kBitstreamType#

class nvidia.nvimgcodec.Jpeg2kBitstreamType#

Members:

J2K

JP2

Jpeg2kProgOrder#

class nvidia.nvimgcodec.Jpeg2kProgOrder#

Members:

LRCP

RLCP

RPCL

PCRL

CPRL

ColorSpec#

class nvidia.nvimgcodec.ColorSpec#

Members:

UNCHANGED

YCC

RGB

GRAY

as_image#

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

Wraps an external buffer as an image and ties the buffer lifetime to the image

Parameters:

  • source – Input DLPack tensor which is encapsulated in a PyCapsule object or other object with __cuda_array_interface__, __array_interface__ or __dlpack__ and __dlpack_device__ methods.

  • cuda_stream – An optional cudaStream_t represented as a Python integer, upon which synchronization must take place in the created Image.

Returns:

nvimgcodec.Image

as_images#

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

Wraps all an external buffers as an images and ties the buffers lifetime to the images

Parameters:

  • sources – List of input DLPack tensors which is encapsulated in a PyCapsule objects or other objects with __cuda_array_interface__, __array_interface__ or __dlpack__ and __dlpack_device__ methods.

  • cuda_stream – An optional cudaStream_t represented as a Python integer, upon which synchronization must take place in created Image.

Returns:

List of nvimgcodec.Image’s

from_dlpack#

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

Zero-copy conversion from a DLPack tensor to a image.

Parameters:

  • source – Input DLPack tensor which is encapsulated in a PyCapsule object or other (array) object with __dlpack__ and __dlpack_device__ methods.

  • cuda_stream – An optional cudaStream_t represented as a Python integer, upon which synchronization must take place in created Image.

Returns:

nvimgcodec.Image