Python API#

nvImageCodec Python API reference

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

Backend#

class nvidia.nvimgcodec.Backend#

Class representing the backend configuration for image processing tasks.

__init__(*args, **kwargs)#

Overloaded function.

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

Default constructor initializes the backend with GPU_ONLY backend kind and default parameters.

  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.

    Args:

    backend_kind: Specifies the type of backend (e.g., GPU_ONLY, CPU_ONLY).

    load_hint: Fraction of the batch samples that will be processed by this backend (default is 1.0). This is just a hint for performance balancing, so particular extension can ignore it and work on all images it recognizes.

    load_hint_policy: Policy for using the load hint, affecting how processing is distributed.

  2. __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.

    Args:

    backend_kind: Type of backend (e.g., GPU_ONLY, CPU_ONLY).

    backend_params: Additional parameters that define how the backend should operate.

property backend_kind#

The backend kind determines whether processing is done on GPU, CPU, or a hybrid of both.

property backend_params#

Backend parameters include detailed configurations that control backend behavior and performance.

property load_hint#

Load hint is a fraction representing the portion of the workload assigned to this backend. Adjusting this may optimize resource use across available backends.

property load_hint_policy#

The load hint policy defines how the load hint is interpreted, affecting dynamic load distribution.

BackendKind#

class nvidia.nvimgcodec.BackendKind#

Enum representing backend kinds used in nvImageCodec for decoding/encoding operations.

This enum helps specify where (CPU, GPU, both, or GPU hardware engine) the image processing tasks are executed.

Members:

CPU_ONLY :

Backend kind specifying that decoding/encoding is executed only on CPU.

GPU_ONLY :

Backend kind specifying that decoding/encoding is executed only on GPU.

HYBRID_CPU_GPU :

Backend kind specifying that decoding/encoding is executed on both CPU and GPU.

HW_GPU_ONLY :

Backend kind specifying that decoding/encoding is executed on GPU dedicated hardware engine.

LoadHintPolicy#

class nvidia.nvimgcodec.LoadHintPolicy#

Enum representing load hint policies for backend batch processing.

Load hint is used to calculate the fraction of the batch items that will be picked by this backend and the rest of the batch items would be passed to fallback codec. This is just a hint and a particular implementation can choose to ignore it.

Members:

IGNORE :

Ignore the load hint.

In this policy, the backend does not take the load hint into account when determining batch processing. It functions as if no hint was provided.

FIXED :

Use the load hint to determine a fixed batch size.

This policy calculates the backend batch size based on the provided load hint once, and uses this fixed batch size for processing.

ADAPTIVE_MINIMIZE_IDLE_TIME :

Adaptively use the load hint to minimize idle time.

This policy uses the load hint as an initial starting point and recalculates on each iteration to dynamically adjust and reduce the idle time of threads, optimizing overall resource utilization.

BackendParams#

class nvidia.nvimgcodec.BackendParams#

Class for configuring backend parameters like load hint and load hint policy.

__init__(*args, **kwargs)#

Overloaded function.

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

    Creates a BackendParams object with default settings.

    By default, the load hint is set to 1.0 and the load hint policy is set to a fixed value.

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

    Creates a BackendParams object with specified load parameters.

    Args:

    load_hint: A float representing the 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 a hint for performance balancing, so particular extension can ignore it and work on all images it recognizes.

    load_hint_policy: Defines how the load hint is used. Different policies can dictate whether to ignore, fix, or adaptively change the load hint.

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 a hint for performance balancing, so particular extension can ignore it and work on all images it recognizes.

property load_hint_policy#

Defines how to use the load hint.

This property controls the interpretation of load hints, with options to ignore, use as fixed or adaptively alter the hint according to workload.

CodeStream#

class nvidia.nvimgcodec.CodeStream#

Class representing a coded stream of image data.

This class provides access to image informations such as dimensions, codec, and tiling details. It supports initialization from bytes, numpy arrays, or file path.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.CodeStream, bytes: bytes) -> None

    Initialize a CodeStream using bytes as input.

    Args:

    bytes: The byte data representing the encoded stream.

  2. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.CodeStream, array: numpy.ndarray[numpy.uint8]) -> None

    Initialize a CodeStream using a numpy array of uint8 as input.

    Args:

    array: The numpy array containing the encoded stream.

  3. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.CodeStream, filename: os.PathLike) -> None

    Initialize a CodeStream using a file path as input.

    Args:

    filename: The file path to the encoded stream data.

property channels#

The number of channels in the image.

property codec_name#

Image format.

property dtype#

Data type of samples.

property height#

The vertical dimension of the entire image in pixels.

property num_tiles_x#

The number of tiles arranged along the horizontal axis of the image.

property num_tiles_y#

The number of tiles arranged along the vertical axis of the image.

property precision#

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

property tile_height#

The vertical dimension of each individual tile within the image.

property tile_width#

The horizontal dimension of each individual tile within the image.

property width#

The horizontal dimension of the entire image in pixels.

DecodeSource#

class nvidia.nvimgcodec.DecodeSource#

Class representing a source for decoding, which includes the image code stream to decode and an optional region within the image.

__init__(*args, **kwargs)#

Overloaded function.

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.DecodeSource, code_stream: nvidia.nvimgcodec.nvimgcodec_impl.CodeStream, region: Optional[nvidia.nvimgcodec.nvimgcodec_impl.Region] = None) -> None

Constructor initializing DecodeSource with a code stream and an optional region to specify a subsection of the image to decode.

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.DecodeSource, array: numpy.ndarray[numpy.uint8], region: Optional[nvidia.nvimgcodec.nvimgcodec_impl.Region] = None) -> None

Constructor initializing DecodeSource with a numpy array and an optional region to decode specific parts of the image.

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.DecodeSource, bytes: bytes, region: Optional[nvidia.nvimgcodec.nvimgcodec_impl.Region] = None) -> None

Constructor initializing DecodeSource with byte data and an optional region to decode specific parts of the image.

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.DecodeSource, filename: os.PathLike, region: Optional[nvidia.nvimgcodec.nvimgcodec_impl.Region] = None) -> None

Constructor initializing DecodeSource with filename pointing to the file with image and an optionally region to decode specific parts of the image.

property code_stream#

Returns the code stream to be decoded into an image.

property region#

Returns the region of the image that will be decoded, if specified; otherwise, returns None.

ChromaSubsampling#

class nvidia.nvimgcodec.ChromaSubsampling#

Enum representing different types of chroma subsampling.

Chroma subsampling is the practice of encoding images by implementing less resolution for chroma information than for luma information. This is based on the fact that the human eye is more sensitive to changes in brightness than color.

Members:

CSS_444 :

No chroma subsampling. Each pixel has a corresponding chroma value (full color resolution).

CSS_422 :

Chroma is subsampled by a factor of 2 in the horizontal direction. Each line has its chroma sampled at half the horizontal resolution of luma.

CSS_420 :

Chroma is subsampled by a factor of 2 both horizontally and vertically. Each block of 2x2 pixels shares a single chroma sample.

CSS_440 :

Chroma is subsampled by a factor of 2 in the vertical direction. Each column has its chroma sampled at half the vertical resolution of luma.

CSS_411 :

Chroma is subsampled by a factor of 4 in the horizontal direction. Each line has its chroma sampled at quarter the horizontal resolution of luma.

CSS_410 :

Chroma is subsampled by a factor of 4 horizontally and a factor of 2 vertically. Each line has its chroma sampled at quarter the horizontal and half of the vertical resolution of luma.

CSS_GRAY :

Grayscale image. No chroma information is present.

CSS_410V :

Chroma is subsampled by a factor of 4 horizontally and a factor of 2 vertically. Each line has its chroma sampled at quarter the horizontal and half of the vertical resolution of luma. Comparing to 4:1:0, this variation modifies how vertical sampling is handled. While it also has one chroma sample for every four luma samples horizontally, it introduces a vertical alternation in how chroma samples are placed between rows.

DecodeParams#

class nvidia.nvimgcodec.DecodeParams#

Class to define parameters for image decoding operations.

__init__(*args, **kwargs)#

Overloaded function.

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

Default constructor that initializes the DecodeParams object with default settings.

  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 parameters to control the decoding process.

    Args:

    apply_exif_orientation: Boolean flag to apply EXIF orientation if available. Defaults to True.

    color_spec: Desired color specification for decoding. Defaults to sRGB.

    allow_any_depth: Boolean flag to allow any native bit depth. If not enabled, the dynamic range is scaled to uint8. Defaults to False.

property allow_any_depth#

Boolean property to permit any native bit depth during decoding.

When set to True, it allows decoding of images with their native bit depth. If False, the pixel values are scaled to the 8-bit range (0-255). Defaults to False.

property apply_exif_orientation#

Boolean property to enable or disable applying EXIF orientation during decoding.

When set to True, the image is rotated and/or flipped according to its EXIF orientation metadata if present. Defaults to True.

property color_spec#

Property to get or set the color specification for the decoding process.

This determines the color space or color profile to use during decoding. For instance, sRGB is a common color specification. Defaults to sRGB.

Decoder#

class nvidia.nvimgcodec.Decoder#

Decoder for image decoding operations. It provides methods to decode images from various sources such as files or data streams. The decoding process can be configured with parameters like the applied backend or execution settings.

__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. There is None in returned list on positions which could not be decoded.

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. There is None in returned list on positions which could not be decoded.

JpegEncodeParams#

class nvidia.nvimgcodec.JpegEncodeParams#

Class to define parameters for JPEG image encoding operations. It provides settings to configure JPEG encoding such as enabling progressive encoding and optimizing Huffman tables.

__init__(*args, **kwargs)#

Overloaded function.

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

Default constructor that initializes the JpegEncodeParams object with default settings.

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

    Constructor with parameters to control the JPEG encoding process.

    Args:

    progressive: Boolean flag to use progressive JPEG encoding. Defaults to False.

    optimized_huffman: Boolean flag to use optimized Huffman tables for JPEG encoding. Defaults to False.

property optimized_huffman#

Boolean property to enable or disable the use of optimized Huffman tables in JPEG encoding.

When set to True, the JPEG encoding process will use optimized Huffman tables which produce smaller file sizes but may require more processing time. Defaults to False.

property progressive#

Boolean property to enable or disable progressive JPEG encoding.

When set to True, the encoded JPEG will be progressive, meaning it can be rendered in successive waves of detail. Defaults to False.

Jpeg2kEncodeParams#

class nvidia.nvimgcodec.Jpeg2kEncodeParams#

Class to define parameters for JPEG2000 image encoding operations.

__init__(*args, **kwargs)#

Overloaded function.

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

Default constructor that initializes the Jpeg2kEncodeParams object with default settings.

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

    Constructor with parameters to control the JPEG2000 encoding process.

    Args:

    reversible: Boolean flag to use reversible JPEG2000 transform. Defaults to False (irreversible).

    code_block_size: Tuple representing the height and width of code blocks in the encoding. Defaults to (64, 64).

    num_resolutions: Number of resolution levels for the image. Defaults to 6.

    bitstream_type: Type of JPEG2000 bitstream, either raw codestream or JP2 container. Defaults to JP2.

    prog_order: Progression order for the JPEG2000 encoding. Defaults to RPCL (Resolution-Position-Component-Layer).

property bitstream_type#

Property to get or set the JPEG2000 bitstream type.

Determines the type of container or codestream for the encoded image. Defaults to JP2.

property code_block_size#

Property to get or set the code block width and height for encoding.

Defines the size of code blocks used in JPEG2000 encoding. Defaults to (64, 64).

property num_resolutions#

Property to get or set the number of resolution levels.

Determines the number of levels for the image’s resolution pyramid. Each additional level represents a halving of the resolution. Defaults to 6.

property prog_order#

Property to get or set the progression order for the JPEG2000 encoding.

Specifies the order in which the encoded data is organized. It can affect decoding performance and streaming. Defaults to RPCL.

property reversible#

Boolean property to enable or disable the reversible JPEG2000 transform.

When set to True, uses a reversible transform ensuring lossless compression. Defaults to False (irreversible).

EncodeParams#

class nvidia.nvimgcodec.EncodeParams#

Class to define parameters for image encoding operations.

__init__(*args, **kwargs)#

Overloaded function.

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

Default constructor that initializes the EncodeParams object with default settings.

  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 parameters to control the encoding process.

    Args:

    quality (float): Compression quality, 0-100. Defaults to 95. For WebP, values >100 indicate lossless compression.

    target_psnr (float): Target Peak Signal-to-Noise Ratio for encoding, applicable to some codecs (At present, JPEG2000 only). Defaults to 50.

    color_spec (ColorSpec): Output color specification. Defaults to UNCHANGED.

    chroma_subsampling (ChromaSubsampling): Chroma subsampling format. Defaults to CSS_444.

    jpeg_encode_params (JpegEncodeParams): Optional JPEG specific encoding parameters.

    jpeg2k_encode_params (Jpeg2kEncodeParams): Optional JPEG2000 specific encoding parameters.

property chroma_subsampling#

Specifies the chroma subsampling format for encoding. Defaults to CSS_444 so not chroma subsampling.

property color_spec#

Defines the expected color specification for the output. Defaults to ColorSpec.UNCHANGED.

property jpeg2k_params#

Optional, additional JPEG2000-specific encoding parameters.

property jpeg_params#

Optional, additional JPEG-specific encoding parameters.

property quality#

Quality value for encoding, ranging from 0 to 100. Defaults to 95.

For WebP, a value greater than 100 signifies lossless compression.

property target_psnr#

Desired Peak Signal-to-Noise Ratio (PSNR) target for the encoded image. Defaults to 50.

Encoder#

class nvidia.nvimgcodec.Encoder#

Encoder for image encoding operations. It allows converting images to various compressed formats or save them to files. The encoding process can be customized with different parameters and options.

__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) -> object

    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:

    Encoded file name, or None if the input image could not be encoded for any reason.

  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) -> list[object]

    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 encoded file names. If an image could not be encoded for any reason, the corresponding position in the list will contain None.

ImageBufferKind#

class nvidia.nvimgcodec.ImageBufferKind#

Enum representing 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.

At present, the image must always have a three-dimensional shape in the HWC layout (height, width, channels), which is also known as the interleaved format, and be stored as a contiguous array in C-style.

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. This indicates whether the data is stored as strided device or host memory.

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 no 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#

The data type (dtype) of the image samples.

property height#

The height of the image in pixels.

property ndim#

The number of dimensions in the image.

property precision#

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

property shape#

The shape of the image.

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,

  • Image. (upon which synchronization must take place in created)

Returns:

DLPack tensor which is encapsulated in a PyCapsule object.

property width#

The width of the image in pixels.

Jpeg2kBitstreamType#

class nvidia.nvimgcodec.Jpeg2kBitstreamType#

Enum to define JPEG2000 bitstream types.

This enum identifies the bitstream type for JPEG2000, which may be either a raw J2K codestream or a JP2 container format that can include additional metadata.

Members:

J2K : JPEG2000 codestream format

JP2 : JPEG2000 JP2 container format

Jpeg2kProgOrder#

class nvidia.nvimgcodec.Jpeg2kProgOrder#

Enum representing progression orders in the JPEG2000 standard.

Members:

LRCP :

Layer-Resolution-Component-Position progression order.

This progression order encodes data by layer first, then by resolution, component, and position, optimizing for scalability in quality.

RLCP :

Resolution-Layer-Component-Position progression order.

This progression order encodes data by resolution first, followed by layer, component, and position, optimizing for scalability in resolution.

RPCL :

Resolution-Position-Component-Layer progression order.

This progression order encodes data by resolution first, then by position, component, and layer, which is useful for progressive transmission by resolution.

PCRL :

Position-Component-Resolution-Layer progression order.

This progression order encodes data by position first, followed by component, resolution, and layer. It is beneficial for progressive transmission by spatial area.

CPRL :

Component-Position-Resolution-Layer progression order.

This progression order encodes data by component first, then by position, resolution, and layer, optimizing for scalability in component access.

ColorSpec#

class nvidia.nvimgcodec.ColorSpec#

Enum representing color specification for image.

Members:

UNCHANGED : Use the color specification unchanged from the source.

YCC : Use the YCBCr color space.

RGB : Use the standard RGB color space.

GRAY : Use the grayscale color space.

Region#

class nvidia.nvimgcodec.Region#

Class representing a region of interest within an image.

The dimensions are oriented such that the top-left corner is (0,0).

__init__(*args, **kwargs)#

Overloaded function.

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

Default constructor that initializes an empty Region object.

  1. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Region, start_y: int, start_x: int, end_y: int, end_x: int) -> None

    Constructor that initializes a Region with specified start and end coordinates.

    Args:

    start_y: Starting Y coordinate.

    start_x: Starting X coordinate.

    end_y: Ending Y coordinate.

    end_x: Ending X coordinate.

  2. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Region, start: list[int], end: list[int]) -> None

    Constructor that initializes a Region with start and end coordinate lists.

    Args:

    start: List of starting coordinates.

    end: List of ending coordinates.

  3. __init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Region, start: tuple, end: tuple) -> None

    Constructor that initializes a Region with start and end coordinate tuples.

    Args:

    start: Tuple of starting coordinates.

    end: Tuple of ending coordinates.

property end#

Property to get the end coordinates of the Region.

Returns:

A list of ending coordinates.

property ndim#

Property to get the number of dimensions in the Region.

Returns:

The number of dimensions.

property start#

Property to get the start coordinates of the Region.

Returns:

A list of starting coordinates.

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.

At present, the image must always have a three-dimensional shape in the HWC layout (height, width, channels), which is also known as the interleaved format, and be stored as a contiguous array in C-style.

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.

At present, the image must always have a three-dimensional shape in the HWC layout (height, width, channels), which is also known as the interleaved format, and be stored as a contiguous array in C-style.

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