Metadata-Version: 2.2
Name: nvidia-vfx
Version: 0.1.0.0
Summary: Python bindings for NVIDIA Video Effects SDK
Author: NVIDIA Python Bindings Contributors
License: LicenseRef-NvidiaProprietary
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# nvidia-vfx Python Wheel README

## nvidia-vfx

`nvidia-vfx` provides Python bindings for the **NVIDIA VFX SDK**. It includes the **VideoSuperRes** effect, so you can add AI-based upscaling, denoising, and deblurring to your video pipelines entirely from Python.

## Features

- **Video Super Resolution** – upscale and enhance SDR video up to 4x while reducing compression artifacts.
- **Same-resolution denoise/deblur** – set output dimensions equal to input and use denoise or deblur quality levels to clean noisy or blurry footage without changing resolution.  
- **Zero-copy interop** – exchange data with PyTorch, CuPy, and other frameworks via the DLPack protocol.  
- **GPU-accelerated** – runs entirely on NVIDIA GPUs with Tensor Cores for real-time or near-real-time performance on supported hardware.

## Requirements

- **Python:** 3.10 or later
- **GPU:** NVIDIA GPU with Tensor Cores (Turing, Ampere, Ada, Blackwell, or Hopper architecture)
- **GPU driver:**
  - Windows: 570.65 or later (for Tesla Compute Cluster (TCC) devices, 595 or later is required)
  - Linux: 570.190+, 580.82+, or 590.44+
- **OS:**
  - Windows: 64-bit Windows 10 or later
  - Linux: Ubuntu 20.04, 22.04, 24.04, Debian 12, or RHEL 8/9

## Installation

```bash
pip install nvidia-vfx
```

This installs the Python bindings; at runtime `nvidia-vfx` loads the NVIDIA VFX libraries bundled in the wheel.

## Quick start (PyTorch)

```python
import torch
from nvvfx import VideoSuperRes

# Example input: 1080p RGB frame on CUDA in [0, 1] range
frame = torch.rand(3, 1080, 1920, device="cuda", dtype=torch.float32)

# Create effect with standard HIGH quality (default)
vsr = VideoSuperRes(quality=VideoSuperRes.QualityLevel.HIGH)
# Set output dimensions (e.g. 2x upscale)
vsr.output_width = 3840   # 1920 * 2
vsr.output_height = 2160  # 1080 * 2
vsr.load()

# Run Video Super Resolution; returns DLPack capsule
result = vsr.run(frame)
# IMPORTANT: convert and clone before reusing the effect
out = torch.from_dlpack(result.image).clone()
print(out.shape)   # -> (3, 2160, 3840)
```

## Quick start (CuPy)

```python
import cupy as cp
from nvvfx import VideoSuperRes

# Example input: 720p RGB frame on CUDA in [0, 1] range
frame = cp.random.rand(3, 720, 1280, dtype=cp.float32)

# Same-resolution denoise: output dimensions = input dimensions
vsr = VideoSuperRes(quality=VideoSuperRes.QualityLevel.DENOISE_HIGH)
vsr.output_width = 1280
vsr.output_height = 720
vsr.load()

result = vsr.run(frame)
# IMPORTANT: convert and copy before the next call
out = cp.from_dlpack(result.image).copy()
print(out.shape)   # -> (3, 720, 1280)
```

## Output dimensions and quality overview

- Set **`output_width`** and **`output_height`** (in pixels), then call **`load()`** before **`run()`**. Input size is inferred from each frame; use output size to control upscaling or same-resolution processing.
- **Upscaling (2x, 3x, 4x):** Set `output_width` and `output_height` to the desired size (e.g. 2x input width and height). Use standard quality levels (e.g. `VideoSuperRes.QualityLevel.HIGH`) or high-bitrate levels for clean sources.
- **Same-resolution (denoise/deblur):** Set `output_width` and `output_height` equal to the input dimensions. Use a `DENOISE_*` or `DEBLUR_*` quality level.
- **`QualityLevel`** is an `IntEnum` (e.g. `VideoSuperRes.QualityLevel`) with values in the range `0–19`, grouped into:  
  - Standard upscaling modes (BICUBIC through ULTRA)  
  - Denoise modes (`DENOISE_LOW` ... `DENOISE_ULTRA`)  
  - Deblur modes (`DEBLUR_LOW` ... `DEBLUR_ULTRA`)  
  - High-bitrate upscaling modes (`HIGHBITRATE_LOW` ... `HIGHBITRATE_ULTRA`)

Pass a `QualityLevel` enum member to the `quality` argument (e.g. `VideoSuperRes.QualityLevel.HIGH`).

## Best practices

- Keep tensors on the GPU and in channels-first RGB `(3, H, W)` format with `float32` values in `[0.0, 1.0]` for optimal performance.
- Use moderate quality levels for interactive previews, and then switch to ULTRA or high-bitrate variants for final renders.
- **`run()`** returns a **`VideoSuperResOutput`** whose `.image` is a DLPack capsule. Convert with `torch.from_dlpack(result.image).clone()` or `cp.from_dlpack(result.image).copy()` and keep that copy before the next **`run()`** so the underlying buffer is not overwritten.

## Documentation

For the complete API reference, parameter details, and advanced usage, refer to the [NVIDIA Video Effects (VFX) Python Bindings Guide](https://docs.nvidia.com/maxine/vfx-python/latest/index.html).

## Changelog

### 0.1.0.0 (first release)

- Initial release of the `nvidia-vfx` Python wheel.
- **Internal VFX SDK version:** 1.2.0.0.
- **Video Super Resolution** – upscale, denoise, and deblur via the `VideoSuperRes` effect.
- Zero-copy interop with PyTorch, CuPy, and other frameworks via the DLPack protocol.
