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.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Backend) -> None
Default constructor
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Backend, backend_kind: nvidia.nvimgcodec.nvimgcodec_impl.BackendKind, load_hint: float = 1.0) -> None
Constructor with parameters
__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.
BackendKind#
- class nvidia.nvimgcodec.BackendKind#
Members:
CPU_ONLY
GPU_ONLY
HYBRID_CPU_GPU
HW_GPU_ONLY
BackendParams#
- class nvidia.nvimgcodec.BackendParams#
- __init__(*args, **kwargs)#
Overloaded function.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.BackendParams) -> None
Default constructor
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.BackendParams, load_hint: bool = 1.0) -> None
Constructor with load_hint 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 codec can ignore this value
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.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams) -> None
Default constructor
__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.
__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”
__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.
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.
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.
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.
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.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.JpegEncodeParams) -> None
Default constructor
__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.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Jpeg2kEncodeParams) -> None
Default constructor
__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.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.EncodeParams) -> None
Default constructor
__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)
- property target_psnr#
Target psnr (default 50)
Encoder#
- class nvidia.nvimgcodec.Encoder#
- __init__(*args, **kwargs)#
Overloaded function.
__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.
__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.
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
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