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.

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

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

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

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

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.

Metadata#

class nvidia.nvimgcodec.Metadata#

Class representing metadata associated with an image.

This class provides access to metadata information such as EXIF data, geographic information, or medical metadata.

__init__(*args, **kwargs)#

Overloaded function.

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

Default constructor that initializes an empty Metadata object.

__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Metadata, kind: nvidia.nvimgcodec.nvimgcodec_impl.MetadataKind, format: nvidia.nvimgcodec.nvimgcodec_impl.MetadataFormat, buffer: bytes) -> None

Constructor that initializes a Metadata object with specified kind, format and buffer.

Args:
kind: The kind of metadata (e.g. EXIF, GEO, medical formats).

format: The format of the metadata (e.g. RAW, JSON, XML).

buffer: The metadata content as bytes.

property buffer#

Property to get the metadata content.

Returns:: The metadata content as bytes.

property buffer_size#

Property to get the size of the metadata buffer in bytes.

Returns:: The size of the metadata buffer.

property format#

Property to get the format of the metadata.

Returns:: The metadata format (e.g. RAW, JSON, XML).

property id#

Property to get the ID of the metadata.

Returns:: The metadata ID. For TIFF tag metadata kind, this is the tag ID. For other metadata kinds, it is reserved for future use.

property kind#

Property to get the kind of metadata.

Returns:: The metadata kind (e.g. EXIF, GEO, medical formats).

property value#

Property to get the metadata value converted to a Python type.

Returns:

BYTE/UNDEFINED: byte or bytes
ASCII: string
SHORT: int or list of ints
LONG: int or list of ints
RATIONAL: tuple (numerator, denominator) or list of tuples
SBYTE: int or list of ints
SSHORT: int or list of ints
SLONG: int or list of ints
SRATIONAL: tuple (numerator, denominator) or list of tuples
FLOAT: float or list of floats
DOUBLE: float or list of floats
LONG8/IFD8: int or list of ints
SLONG8: int or list of ints
Unknown types: raw bytes

Returns None if buffer is empty.

Return type:

The metadata value converted to an appropriate Python type based on the metadata type

property value_count#

Property to get the number of values in the metadata.

Returns:: The number of values. For TIFF tag metadata, this represents the count of values for the tag.

property value_type#

Property to get the type of the metadata when format is RAW.

Returns:: The metadata type (e.g. BYTE, SHORT, LONG, etc.).

MetadataFormat#

class nvidia.nvimgcodec.MetadataFormat#

Enum representing different metadata formats.

The format specifies how the metadata is encoded (e.g. RAW, JSON, XML).

Members:

UNKNOWN :
Unknown metadata format.

RAW :
Raw binary metadata format.

JSON :
JSON metadata format.

XML :
XML metadata format.

XMP :
XMP metadata format.

MetadataKind#

class nvidia.nvimgcodec.MetadataKind#

Enum representing different metadata kinds.

The kind specifies the type of metadata (e.g. EXIF, GEO, medical formats).

Members:

UNKNOWN :
Unknown metadata kind.

TIFF_TAG :
TIFF tag metadata.

ICC_PROFILE :
ICC profile metadata.

EXIF :
EXIF metadata containing camera settings and image capture information. [Reserved for future use]

GEO :
Geographic metadata as in GeoTIFF.

MED_APERIO :
Medical metadata in Aperio format for whole slide imaging.

MED_PHILIPS :
Medical metadata in Philips format for whole slide imaging.

MED_VENTANA :
Medical metadata in Ventana format for whole slide imaging.

MED_LEICA :
Medical metadata in Leica format for whole slide imaging.

MED_TRESTLE :
Medical metadata in Trestle format for whole slide imaging.

MetadataType#

class nvidia.nvimgcodec.MetadataType#

Enum representing different metadata types.

Metadata types as defined for TIFF tag types in TIFF specification.

Members:

UNKNOWN :
Unknown metadata type.

BYTE :
8-bit unsigned integer.

ASCII :
8-bit byte containing 7-bit ASCII code; last byte must be NUL.

SHORT :
16-bit (2-byte) unsigned integer.

LONG :
32-bit (4-byte) unsigned integer.

RATIONAL :
Two LONGs: numerator and denominator.

SBYTE :
8-bit signed (twos-complement) integer.

UNDEFINED :
8-bit byte, value depends on field definition.

SSHORT :
16-bit (2-byte) signed (twos-complement) integer.

SLONG :
32-bit (4-byte) signed (twos-complement) integer.

SRATIONAL :
Two SLONGs: numerator and denominator.

FLOAT :
4-byte IEEE floating point value.

DOUBLE :
8-byte IEEE floating point value.

LONG8 :
8-byte (64-bit) unsigned integer (BigTIFF).

SLONG8 :
8-byte (64-bit) signed integer (BigTIFF).

IFD8 :
8-byte (64-bit) unsigned integer used for offsets (BigTIFF).

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.

__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.
__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.
__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.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.CodeStream, pre_allocated_size: int = 0, pin_memory: bool = True) -> None

Initialize a CodeStream for encoding output.

Args:
pre_allocated_size: The size of the pre-allocated memory. (default: 0)

pin_memory: If True, the output memory will be pinned. (default: True)

property capacity#: The capacity of the internal buffer in bytes.

property codec_name#: Image format.

property color_spec#

Property to get the color specification for the code stream.

This determines the color space or color profile of the image data. For instance, sRGB is a common color specification.

Please notice that color specification of decoded Image depends of color_spec parameter used in decode function so can be different from the one of the code stream.

property dtype#: Data type of samples.

get_sub_code_stream(*args, **kwargs)#

Overloaded function.

get_sub_code_stream(self: nvidia.nvimgcodec.nvimgcodec_impl.CodeStream, image_idx: int = 0, region: Optional[nvidia.nvimgcodec.nvimgcodec_impl.Region] = None) -> nvidia.nvimgcodec.nvimgcodec_impl.CodeStream

Get a sub code stream for a specific image index and optional region.

Args:
image_idx: Index of the image in the code stream. Defaults to 0.

region: Optional region of interest within the image.

Returns:
A new CodeStream object representing the sub code stream.
get_sub_code_stream(self: nvidia.nvimgcodec.nvimgcodec_impl.CodeStream, view: nvidia.nvimgcodec.nvimgcodec_impl.CodeStreamView) -> nvidia.nvimgcodec.nvimgcodec_impl.CodeStream

Get a sub code stream using a CodeStreamView object.

Args:
view: A CodeStreamView object specifying the image index and optional region.

Returns:
A new CodeStream object representing the sub code stream.

property height#: The vertical dimension of the entire image in pixels.

property num_channels#: The overall number of channels in the image across all planes.

property num_images#: The number of images in the code stream.

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 pin_memory#: Whether the internal buffer is pinned.

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

property sample_format#: The sample format of the code stream indicating how color components are matched to channels and channels to planes.

property size#: The size of the compressed bitstream in bytes.

property tile_height#: The vertical dimension of each individual tile within the image.

property tile_offset_x#: The horizontal offset of the tile grid to the left of the image.

property tile_offset_y#: The vertical offset of the tile grid to the top of the image.

property tile_width#: The horizontal dimension of each individual tile within the image.

property view#

The view of this code stream, if it was created as a sub code stream. Contains the image index and optional region of interest.

Returns:: CodeStreamView object if this is a sub code stream, None otherwise.

property width#: The horizontal dimension of the entire image in pixels.

CodeStreamView#

class nvidia.nvimgcodec.CodeStreamView#

Class representing a view into a code stream, specifying which image and region to access.

A code stream view consists of an image index and an optional region of interest.

__init__( self: nvidia.nvimgcodec.nvimgcodec_impl.CodeStreamView, image_idx: int = 0, region: nvidia.nvimgcodec.nvimgcodec_impl.Region | None = None, ) → None#

Constructor that initializes a CodeStreamView with an image index and region.

Parameters:

image_idx – Index of the image in the code stream. Defaults to 0.
region – Optional region of interest within the image.

property image_idx#

Property to get the image index in the code stream.

Returns:: The index of the image.

property region#

Property to get the region of interest.

Returns:: The Region object specifying the area of interest, or None if no region is set.

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.

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

Default constructor that initializes the DecodeParams object with default settings.

__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams, apply_exif_orientation: bool = True, color_spec: nvidia.nvimgcodec.nvimgcodec_impl.ColorSpec = <ColorSpec.SRGB: 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__( self: nvidia.nvimgcodec.nvimgcodec_impl.Decoder, device_id: int = -1, max_num_cpu_threads: int = 0, backends: list[nvidia.nvimgcodec.nvimgcodec_impl.Backend] | None = None, options: str = ':fancy_upsampling=0', ) → None#

Initialize decoder.

Parameters:

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”

decode(*args, **kwargs)#

Overloaded function.

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

Executes decoding of data from a CodeStream handle.

Args:
src: CodeStream object.

image: Optional Image object to reuse for decoding. If provided, the Image’s buffer will be
resized and reused instead of allocating a new Image. Only Images with internally managed buffers can be reused. Defaults to None (create new Image).

params: Decode parameters. Defaults to None (use default parameters).

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

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.CodeStream], *, images: Optional[list[nvidia.nvimgcodec.nvimgcodec_impl.Image]] = None, params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams] = None, cuda_stream: int = 0) -> list[object]

Executes decoding from a batch of CodeStream handles.

Args:
srcs: List of CodeStream objects

images: Optional list of Image objects to reuse for decoding. If provided, the Images’ buffers will be
resized and reused instead of allocating new Images. The list must have the same size as srcs. Only Images with internally managed buffers can be reused. Defaults to None (create new Images).

params: Decode parameters. Defaults to None (use default parameters).

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

Returns:
List of decoded nvimgcodec.Image’s. There is None in returned list on positions which could not be decoded.

get_metadata(*args, **kwargs)#

Overloaded function.

get_metadata(self: nvidia.nvimgcodec.nvimgcodec_impl.Decoder, code_stream: nvidia.nvimgcodec.nvimgcodec_impl.CodeStream, *, kind: Optional[nvidia.nvimgcodec.nvimgcodec_impl.MetadataKind] = None) -> list

Retrieves metadata from a code stream.

Args:
code_stream: The code stream to get metadata from. kind: Optional metadata kind to filter by. If specified, only metadata of that kind will be returned.

Returns:
A list of Metadata objects. If no metadata exists or no metadata matches the specified kind, returns an empty list.
get_metadata(self: nvidia.nvimgcodec.nvimgcodec_impl.Decoder, code_stream: nvidia.nvimgcodec.nvimgcodec_impl.CodeStream, *, id: int, kind: nvidia.nvimgcodec.nvimgcodec_impl.MetadataKind = <MetadataKind.TIFF_TAG: 1>) -> nvidia.nvimgcodec.nvimgcodec_impl.Metadata

Retrieves a specific metadata by ID from a code stream.

Args:
code_stream: The code stream to get metadata from. id: The specific metadata ID to retrieve. kind: Metadata kind. Defaults to TIFF tag kind if not specified.

Returns:
A single Metadata object for the specified id.

Raises:
RuntimeError: If metadata with the specified ID is not found.

read(*args, **kwargs)#

Overloaded function.

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

Executes decoding from a CodeStream (typically created from a file).

Args:
path: CodeStream object (typically from a file path).

image: Optional Image object to reuse for decoding. If provided, the Image’s buffer will be
resized and reused instead of allocating a new Image. Only Images with internally managed buffers can be reused. Defaults to None (create new Image).

params: Decode parameters. Defaults to None (use default parameters).

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

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.CodeStream], *, images: Optional[list[nvidia.nvimgcodec.nvimgcodec_impl.Image]] = None, params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.DecodeParams] = None, cuda_stream: int = 0) -> list[object]

Executes decoding from a batch of CodeStreams (typically created from file paths).

Args:
paths: List of CodeStream objects (typically from file paths).

images: Optional list of Image objects to reuse for decoding. If provided, the Images’ buffers will be
resized and reused instead of allocating new Images. The list must have the same size as paths. Only Images with internally managed buffers can be reused. Defaults to None (create new Images).

params: Decode parameters. Defaults to None (use default parameters).

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

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.

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

Default constructor that initializes the JpegEncodeParams object with default settings.

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

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

Default constructor that initializes the Jpeg2kEncodeParams object with default settings.

__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Jpeg2kEncodeParams, 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>, mct_mode: int = 0, ht: bool = False) -> None

Constructor with parameters to control the JPEG2000 encoding process.

Args:
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).

mct_mode: Integer flag to use multiple component transform. Defaults to 0 (do not use MCT). Valid values are 0 or 1.

ht: Boolean flag to use High-Throughput JPEG2000 encoder. Defaults to False (do not use HT).

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

Boolean property to enable or disable the High-Throughput JPEG2000 encoder.

When set to True, uses the High-Throughput JPEG2000 encoder. Defaults to False.

property mct_mode#

Integer property to set the multiple component transform mode.

When set to 1, uses the multiple component transform (MCT). Defaults to 0.

It can be used to convert SRGB input color space to SYCC for coding efficiency. Irreversible component transformation used with the 9-7 irreversible filter (lossy compression). Reversible component transformation used with the 5-3 reversible filter (lossless compression).

Multiple component transformation can be used only with SRGB input color space and with chroma subsampling 444.

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.

QualityType#

class nvidia.nvimgcodec.QualityType#

Supported quality types (algorithms), which determines how quality_value is interpreted..

Members:

DEFAULT :
Each plugin decides its default quality setting. quality_value is ignored in this case.

LOSSLESS :
Image encoding is reversible and keeps original image quality. quality_value is ignored, except for the CUDA tiff encoder backend, for which quality_value=0 means no compression, and quality_value=1 means LZW compression..

QUALITY :
quality_value is interpreted as JPEG-like quality in range from 1 (worst) to 100 (best).

QUANTIZATION_STEP :
quality_value is interpreted as quantization step (by how much pixel data will be divided). The higher the value, the worse quality image is produced.

PSNR :
quality_value is interpreted as desired Peak Signal-to-Noise Ratio (PSNR) target for the encoded image. The higher the value, the better quality image is produced. Value should be positive.

SIZE_RATIO :
quality_value is interpreted as desired encoded image size ratio compared to original size, should be floating point in range (0.0, 1.0). E.g. value 0.1 means target size of 10% of original image.

EncodeParams#

class nvidia.nvimgcodec.EncodeParams#

Class to define parameters for image encoding operations.

__init__(*args, **kwargs)#

Overloaded function.

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

Default constructor that initializes the EncodeParams object with default settings.

__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.EncodeParams, quality_type: nvidia.nvimgcodec.nvimgcodec_impl.QualityType = <QualityType.DEFAULT: 0>, quality_value: float = 0, color_spec: nvidia.nvimgcodec.nvimgcodec_impl.ColorSpec = <ColorSpec.UNKNOWN: 0>, chroma_subsampling: Optional[nvidia.nvimgcodec.nvimgcodec_impl.ChromaSubsampling] = None, jpeg_encode_params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.JpegEncodeParams] = None, jpeg2k_encode_params: Optional[nvidia.nvimgcodec.nvimgcodec_impl.Jpeg2kEncodeParams] = None, tile_width: Optional[int] = None, tile_height: Optional[int] = None) -> None

Constructor with parameters to control the encoding process.

Args:
quality_type (QualityType): Quality type (algorithm) that will be used to encode image.

quality_value (float): Specifies how good encoded image should look like. Refer to the QualityType enum for the allowed values for each quality type.

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

chroma_subsampling (ChromaSubsampling): Chroma subsampling format. When not specified, defaults to CSS_GRAY for single-channel (grayscale) images and CSS_444 for multi-channel images.

jpeg_encode_params (JpegEncodeParams): Optional JPEG specific encoding parameters.

jpeg2k_encode_params (Jpeg2kEncodeParams): Optional JPEG2000 specific encoding parameters.

tile_width (int): Optional tile width for tiled encoding. When set to a value greater than 0, enables tiled encoding.

tile_height (int): Optional tile height for tiled encoding. When set to a value greater than 0, enables tiled encoding.

property chroma_subsampling#: Specifies the chroma subsampling format for encoding. When not specified, defaults to CSS_GRAY for single-channel (grayscale) images and CSS_444 for multi-channel images.

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_type#: Quality type (algorithm) that will be used to encode image.

property quality_value#: Specifies how good encoded image should look like. Refer to the QualityType enum for the allowed values for each quality type.

property tile_height#

Height of tiles for tiled encoding.

When set to a value greater than 0, enables tiled encoding with the specified tile height.

property tile_width#

Width of tiles for tiled encoding.

When set to a value greater than 0, enables tiled encoding with the specified tile width.

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__( self: nvidia.nvimgcodec.nvimgcodec_impl.Encoder, device_id: int = -1, max_num_cpu_threads: int = 0, backends: list[nvidia.nvimgcodec.nvimgcodec_impl.Backend] | None = None, options: str = '', ) → None#

Initialize encoder.

Parameters:

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.

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

Encode image(s) to CodeStream(s).

Parameters:

image_s – Image to encode or list of images to encode (can be any Python object that can be converted to Image, or a list of such objects)
codec – String that defines the output format e.g.’jpeg2k’. When it is file extension it must include a leading period e.g. ‘.jp2’.
code_stream_s – CodeStream or list of CodeStreams to encode image to. If None, a new CodeStream(s) will be created.
params – Encode parameters.
cuda_stream – An optional cudaStream_t represented as a Python integer, upon which synchronization must take place.

Returns:

CodeStream with encoded image, or None if the input cannot be converted to Image or if encoding failed. For list of images: List of CodeStreams with encoded images. If an input cannot be converted to Image or if encoding failed, the corresponding position will contain None.

Return type:

For single image

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

Encode image to file.

Args:
file_name: File name to save encoded code stream.

image: Image to encode (can be any Python object that can be converted to Image)

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.
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 (can contain any Python objects that can be converted to Image)

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, but rows can have additional padding.

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.

property capacity#: The capacity of the image buffer in bytes.

property color_spec#: Color specification of the image indicating how the color information in image samples should be interpreted.

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 sample_format#: The sample format of the image indicating how color components are matched to channels and channels to planes.

property shape#: The shape of the image.

property size#: The size of the image buffer in bytes.

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 - how the color information in samples should be interpreted.

Members:

UNKNOWN : The color specification is unknown or not specified.

UNCHANGED : The color specification should be left unchanged from the source; equivalent to UNKNOWN.

SYCC : Specifies the sYCC color space (YCbCr with sRGB primaries).

SRGB : Specifies the standard RGB (sRGB) color space.

GRAY : Specifies grayscale (single channel, no color).

CMYK : Specifies the CMYK color space (Cyan, Magenta, Yellow, Black).

YCCK : Specifies the YCCK color space (YCbCr plus Black channel).

PALETTE : Sample data is represented using a palette color map.

ICC_PROFILE : Precise color space is provided in an ICC profile.

UNSUPPORTED : The color specification is unsupported by the library.

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.

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

Default constructor that initializes an empty Region object.

__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Region, start_y: int, start_x: int, end_y: int, end_x: int, out_of_bounds_sample: Union[int, int, float] = 0) -> 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.

out_of_bounds_sample: The sample that will be set for out of bounds region pixels for all components. If not specified, sample value of 0 will be used.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Region, start: list[int], end: list[int], out_of_bounds_sample: Union[int, int, float] = 0) -> None

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

Args:
start: List of starting coordinates.

end: List of ending coordinates.

out_of_bounds_sample: The sample that will be set for out of bounds region pixels for all components If not specified, sample value of 0 will be used.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Region, start: tuple, end: tuple, out_of_bounds_sample: Union[int, int, float] = 0) -> None

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

Args:
start: Tuple of starting coordinates.

end: Tuple of ending coordinates.

out_of_bounds_sample: The sample that will be set for out of bounds region pixels for all components If not specified, sample value of 0 will be used.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Region, start_y: int, start_x: int, end_y: int, end_x: int, out_of_bounds_samples: list[Union[int, int, float]]) -> 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.

out_of_bounds_samples: The list of samples that will be set for out of bounds pixel. List length must be at most 5, for the rest of the channels fill sample of 5th channel will be used. If list is shorter than 5, then fill sample for missing channels will be set to 0.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Region, start: list[int], end: list[int], out_of_bounds_samples: list[Union[int, int, float]]) -> None

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

Args:
start: List of starting coordinates.

end: List of ending coordinates.

out_of_bounds_samples: The list of samples that will be set for out of bounds pixel. List length must be at most 5, for the rest of the channels fill sample of 5th channel will be used. If list is shorter than 5, then fill sample for missing channels will be set to 0.
__init__(self: nvidia.nvimgcodec.nvimgcodec_impl.Region, start: tuple, end: tuple, out_of_bounds_samples: list[Union[int, int, float]]) -> None

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

Args:
start: Tuple of starting coordinates.

end: Tuple of ending coordinates.

out_of_bounds_samples: The list of samples that will be set for out of bounds pixel. List length must be at most 5, for the rest of the channels fill sample of 5th channel will be used. If list is shorter than 5, then fill sample for missing channels will be set to 0.

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

Property to get the out of bounds samples.

Returns:: A list of out of bounds samples.

property start#

Property to get the start coordinates of the Region.

Returns:: A list of starting coordinates.

SampleFormat#

class nvidia.nvimgcodec.SampleFormat#

Enum representing sample format for image. Sample format describes how color components are matched to channels in given order and channels are matched to planes.

Members:

UNKNOWN : Unknown sample format.

P_UNCHANGED : Unchanged planar format.

I_UNCHANGED : Unchanged interleaved format.

P_Y : Y component only (grayscale). For 3-dimensional shape is defined as (1, H, W) and this is only difference with I_Y.

I_Y : Interleaved Y component only (grayscale). For 3-dimensional shape is defined as (H, W, 1) and this is only difference with P_Y.

P_YA : Planar Y component with alpha.

I_YA : Interleaved Y component with alpha.

P_RGB : Planar RGB format.

I_RGB : Interleaved RGB format.

P_BGR : Planar BGR format.

I_BGR : Interleaved BGR format.

P_YUV : YUV planar format.

P_YCC : YCC planar format (alias for P_YUV).

I_YUV : Interleaved YUV format.

I_YCC : Interleaved YCC format (alias for I_YUV).

P_RGBA : Planar RGBA format.

I_RGBA : Interleaved RGBA format.

P_YCCK : Planar YCCK format.

I_YCCK : Interleaved YCCK format.

P_CMYK : Planar CMYK format.

I_CMYK : Interleaved CMYK format.

UNSUPPORTED : Unsupported sample format.

as_image#

nvidia.nvimgcodec.as_image( source: object, cuda_stream: int = 0, *, sample_format: nvidia.nvimgcodec.nvimgcodec_impl.SampleFormat | None = None, color_spec: nvidia.nvimgcodec.nvimgcodec_impl.ColorSpec | None = None, ) → 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.
sample_format – (keyword-only) An optional nvimgcodec.SampleFormat value to override the default sample format inference. When not specified, defaults are based on number of channels: - 1 channel: I_Y (interleaved grayscale) - 2 channels: I_YA (interleaved grayscale with alpha) - 3 channels: I_RGB for interleaved or P_RGB for planar - 4 channels: I_RGBA (interleaved RGBA) - 5+ channels: UNKNOWN
color_spec – (keyword-only) An optional nvimgcodec.ColorSpec value to override the default color space inference. When not specified, defaults are based on number of channels: - 1 channel: GRAY - 2 channels: GRAY - 3 channels: SRGB - 4 channels: SRGB - 5+ channels: UNKNOWN

Returns:

nvimgcodec.Image

as_images#

nvidia.nvimgcodec.as_images( sources: list[object], cuda_stream: int = 0, *, sample_format: nvidia.nvimgcodec.nvimgcodec_impl.SampleFormat | None = None, color_spec: nvidia.nvimgcodec.nvimgcodec_impl.ColorSpec | None = None, ) → 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.
sample_format – (keyword-only) An optional nvimgcodec.SampleFormat value to override the default sample format inference. When not specified, defaults are based on number of channels: - 1 channel: I_Y (interleaved grayscale) - 2 channels: I_YA (interleaved grayscale with alpha) - 3 channels: I_RGB for interleaved or P_RGB for planar - 4 channels: I_RGBA (interleaved RGBA) - 5+ channels: UNKNOWN
color_spec – (keyword-only) An optional nvimgcodec.ColorSpec value to override the default color space inference. When not specified, defaults are based on number of channels: - 1 channel: GRAY - 2 channels: GRAY - 3 channels: SRGB - 4 channels: SRGB - 5+ channels: UNKNOWN

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