Getting Started

This section guides you step-by-step how to decode and encode images on the GPU using the nvImageCodec APIs. Before getting started, please review the pre-requisites. Once reviewed, head over to the samples’ section which showcases various nvImageCodec samples.

Note

Throughout this document, the terms “CPU” and “Host” are used synonymously. Similarly, the terms “GPU” and “Device” are synonymous.

Thread Safety

Not all nvImageCodec types are thread safe. For user-provided allocators (fields in nvimgcodecExecutionParams_t structure), the user needs to ensure thread safety.

Pre-requisites

Following are the required dependencies to compile nvImageCodec samples.

• Ubuntu >= 20.04

• NVIDIA driver >= 530.30.02

• CUDA Toolit >= 12.1

• Supported systems:

  • Linux (Ubuntu >= 20.04, RHEL >= 8, and other PEP600 manylinux_2_28 compatible platforms)

  • WSL2 with Ubuntu >= 20.04

C++ Samples’ Dependencies:

• CMake >= 3.18

• gcc >= 14

Python Samples’ Dependencies:

• Torch

• Torchvision

• cuPy

• cuCIM

• CV-CUDA

Samples

The next section documents the samples showing various use cases across two different types APIs available to consume nvImageCodec functionality:

• C API samples
  • Single image decode
  • Single image encode
• Python API samples
  • Basics
    • Passing decoding parameters
    • Passing encoding parameters
    • Support of __cuda_array_interface__
    • Support of __array_interface__
      • Parsing image information without decoding
      • Encode Jpeg2000 with tiles
  • Batch processing
  • Code stream and partial (ROI) decoding
    • Out of bounds region decoding
    • Exploiting Tile Geometry
  • Sliding window decoding with tile cache
    • Tile access heatmap
      • Bounded Cache: LRU Eviction Policy
    • Choosing the cache capacity
  • CuPy interoperability
    • DLPack
    • Specifying sample_format and color_spec
      • Default format inference
      • Overriding format inference
      • Format validation
      • Using with as_images
  • cuCIM interoperability
  • CV-CUDA interoperability
    • Resnet50 classification example from cv-cuda
  • Tensorflow interoperability
  • Torch interoperability
    • Interoperability between nvImageCodec and Torch using DLPack
    • Interoperability between nvImageCodec and Torch using __cuda_array_interface__
    • Simplified version by passing troch tensor directly to write function
  • Multi-image
  • Advanced multi-image (SubIFDs and Pagination)
    • Setup
    • Part 1: SubIFD Access (Thumbnails)
    • Part 2: Pagination
    • Part 3: SubIFDs in OME-TIFF (Pyramid Levels)
  • Metadata extraction
    • Geo
    • Aperio
    • Philips
    • Leica
    • Trestle
    • Ventana
    • Generic tiff tag reading
    • List all available TIFF tags
    • Use PIL.TiffTags together with nvImageCodec generic Tiff tag reading
  • Transcode
    • Lossless uint8
    • Lossless uint16
    • Lossless int16
    • Lossess uint16 with alpha channel
    • Lossy uint8
  • Accelerated DICOM decoding and encoding
    • Getting Started with pydicom Plugin
      • Supported Transfer Syntaxes
      • How to Use
      • Understanding the Results
    • Advanced Batch Decoding
      • Advanced Acceleration
      • Key Insights
    • Transcoding to HTJ2K and Multi-Frame
      • Load DICOM Series
      • Transcode to HTJ2K with transcode_datasets_to_htj2k()
      • Create Multi-Frame DICOM with convert_to_enhanced_dicom()
      • Verify Data Integrity
    • Overview
    • Supported Transfer Syntaxes
  • Reuse resources (Image and CodeStream)
    • Reusing Image for multiple decoding operations
    • Reusing CodeStream for multiple encoding operations
    • Reusing externally managed buffers (from CuPy or NumPy)

Decoder and encoder creation accept an optional options string to tune behavior (e.g. :num_cuda_streams=4 or decoder-specific options). See Codec options for the format and the full list of decoder and encoder options.

Refer to the Installation docs for the sample installation guide using *.deb or *.tar installers. Refer to the sample README for instructions to compile samples from the source.