Metadata-Version: 2.4
Name: pixtreme
Version: 0.9.0
Summary: pixtreme: A High-Performance Graphics Library with CUDA Support
Project-URL: repository, https://github.com/sync-dev-org/pixtreme
Project-URL: issues, https://github.com/sync-dev-org/pixtreme/issues
Author-email: minamik <mia@sync.dev>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: GPU :: NVIDIA CUDA :: 12
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: pixtreme-core>=0.9.0
Provides-Extra: aces
Requires-Dist: pixtreme-aces>=0.9.0; extra == 'aces'
Provides-Extra: all
Requires-Dist: pixtreme-aces>=0.9.0; extra == 'all'
Requires-Dist: pixtreme-draw>=0.9.0; extra == 'all'
Requires-Dist: pixtreme-filter>=0.9.0; extra == 'all'
Requires-Dist: pixtreme-upscale[tensorrt]>=0.9.0; extra == 'all'
Provides-Extra: draw
Requires-Dist: pixtreme-draw>=0.9.0; extra == 'draw'
Provides-Extra: filter
Requires-Dist: pixtreme-filter>=0.9.0; extra == 'filter'
Provides-Extra: full
Requires-Dist: pixtreme-aces>=0.9.0; extra == 'full'
Requires-Dist: pixtreme-draw>=0.9.0; extra == 'full'
Requires-Dist: pixtreme-filter>=0.9.0; extra == 'full'
Requires-Dist: pixtreme-upscale[tensorrt]>=0.9.0; extra == 'full'
Provides-Extra: upscale
Requires-Dist: pixtreme-upscale>=0.9.0; extra == 'upscale'
Description-Content-Type: text/markdown

# 🚀 pixtreme

> **Blazing-fast GPU-accelerated image processing for Python**

[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![CUDA](https://img.shields.io/badge/CUDA-12.x-green.svg)](https://developer.nvidia.com/cuda-downloads)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/pixtreme.svg)](https://pypi.org/project/pixtreme/)

## 🌟 Highlights

- **⚡ Lightning Fast**: CUDA-optimized kernels deliver real-time performance
- **🎨 Professional Color Pipeline**: Full ACES workflow, 3D LUTs, 10-bit precision
- **🧠 AI-Ready**: Seamless integration with ONNX, PyTorch, and TensorRT
- **🔗 Framework Interop**: NumPy, CuPy, PyTorch, and `nvimgcodec.Image` support
- **📊 Extensive Format Support**: OpenEXR, JPEG, PNG, TIFF, and more

## 📋 Table of Contents

- [Breaking Changes](#breaking-changes)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
- [Performance Notes](#performance-notes)
- [License](#license)

## ⚠️ Breaking Changes

### v0.9.0: Fail-Fast Validation, CUDA 12.9 Modernization & Structural Hygiene (2026-07-13)

**🔥 BREAKING RELEASE**: This release consolidates three milestones — correctness fixes, platform modernization, and structural hygiene. Many calls that previously succeeded silently (often producing corrupt results) now raise exceptions, several APIs changed signature, and the dependency baseline moved to CUDA 12.9.

**Package structure**:
- **`pixtreme-legacy` has been discontinued** (removed from the workspace). The five `_cp`-suffix APIs (`apply_lut_cp`, `uyvy422_to_ycbcr444_cp`, `ndi_uyvy422_to_ycbcr444_cp`, `yuv420p_to_ycbcr444_cp`, `yuv422p10le_to_ycbcr444_cp`) are no longer provided. Migrate to the suffix-free core APIs
- The meta package's `legacy` extra was removed; `full` is now a compatibility alias identical to `all`

**Fail-fast input validation** — calls that previously executed (often with broken output) now raise `ValueError`:
- `median_blur`: ksize must be odd 3–7 (previously ksize>7 ran with a buffer overflow after a warning; 1 / even / negative were unvalidated)
- `box_blur` / `gaussian_blur`: even or non-positive ksize rejected (gaussian previously incremented even ksize silently; box_blur ran with broken DC gain)
- `gaussian_blur`: custom kernel length/dtype mismatch rejected
- Morphology (all 7 operations): invalid structuring elements (empty / non-int32 / even / non-square / non-binary) rejected (previously float SEs etc. were accepted silently)
- `canny`: negative thresholds rejected
- `clahe`: `tile_grid_size` exceeding image dimensions rejected
- `yuv420p_to_ycbcr444`: interpolation not in {0, 1} rejected (previously returned uninitialized memory)
- `imread` / `imdecode`: unknown dtype tokens now raise `ValueError` (`imread` previously passed them through, `imdecode` silently fell back to float32). `imread` validates dtype before the path
- Exception-type unification: `equalize_hist` / `clahe` / `laplacian` non-float32 rejection is now `ValueError` (was `TypeError`); all 15 strict float32 filter APIs share a unified message pointing to `to_float32()`
- Example: a call like `create_rounded_mask(blur_size=10)` (even value) now raises

**Output changes (corrections of wrong images)** — same calls, different (now correct) pixels:
- `sobel` ksize=7 derivative coefficients now match OpenCV
- `canny` edges thin to 1 pixel on equal-magnitude plateaus
- `clahe` includes trailing pixels in tile statistics for non-divisible shapes (reflect-padded fixed tiles)
- `morphology_close` / `morphology_blackhat` border pixels (neutral border handling)
- mitchell / bicubic resize for non-square output (coordinate fix); mitchell 4-channel output
- `ycbcr_full_to_legal` / `ycbcr_legal_to_full` work for the first time (previously raised CompileException on first call)
- `ndi_uyvy422_to_ycbcr444(use_bilinear=False)` chroma interpolation on the right half of the frame
- ONNX / TensorRT upscale backends scale non-float32 input via `to_float32()` + [0, 1] clip instead of a raw cast (**uint8 / uint16 numeric results change**; now the same contract as the Torch backend)

**Upscale contract changes**:
- `TorchUpscaler` rejects legacy full-module checkpoints by default (`weights_only=True`). Pass `allow_unsafe_checkpoint=True` for trusted checkpoints, or convert to state_dict / safetensors. `.safetensors` is newly supported
- `OnnxUpscaler` no longer falls back to CPU: the CUDA Execution Provider is required, and initialization failures raise an actionable `RuntimeError` (the silent CPU fallback and type-inconsistency CPU retry were removed)
- `onnx_to_trt` / `onnx_to_trt_dynamic_shape` / `onnx_to_trt_fixed_shape`: `precision` accepts only `fp32` / `tf32` (TensorRT 11 is strongly typed; `fp16` etc. raise `ValueError`). **The default changed from `fp16` to `fp32`** — bake FP16 into the ONNX tensor dtypes if you need an FP16 engine
- `TrtUpscaler`: engine deserialize / execution-context failures raise `RuntimeError` (previously `None` passed through and crashed later); only single-input / single-output engines are accepted
- `TorchUpscaler` / `TrtUpscaler` missing-input error message unified to `model_path or model_bytes is required`

**API signature changes**:
- `torch_to_onnx(model_path, onnx_path, input_shape, dynamic_shapes, precision, device)`: `dynamic_axes` / `opset_version` removed in favor of `dynamic_shapes` (dynamo exporter format); exporter is dynamo=True, opset 20
- `onnx_to_onnx_dynamic(input_path, output_path, irver)`: `opset` argument removed (opset 20 contract, previously capped at 19)
- `resize(src=)` / `affine_transform(src=)` / `tile_image(input_image=)`: keyword is now `image=` (old keywords removed)
- `uyvy422_to_ycbcr444`: positional argument order changed `(height, width)` → `(width, height)`
- `corner_harris(blockSize=)` → `block_size=` (no compatibility shim)
- `TrtUpscaler.get(input_frame=)` → `get(image=)` (`image` unified across all three backends)

**dtype vocabulary**:
- `DType` static vocabulary moved from short forms (`fp16` / `fp32` / `fp64`) to NumPy forms (`float16` / `float32` / `float64`); short forms remain accepted as runtime aliases
- `imread` / `imdecode` default token spelling is now `float32` (result dtype is float32, as before)
- `to_dtype` newly dispatches `float64` / `fp64` (previously `ValueError`)

**Logging** — stdout/stderr prints replaced by package loggers (quiet by default; configure logging handlers/levels to see diagnostics):
- `read_lut` exception prints → `pixtreme_core` logger
- model conversion / TensorRT runtime progress and diagnostics → `pixtreme_upscale.*` loggers

**Removed**:
- `pixtreme_core.transform.subsample_flattened` / `subsample_optimized_v2` modules (unpublished alternate implementations; direct imports fail)

**Dependency baseline (CUDA 12.9)**:
- torch / torchvision wheel baseline: cu126 → cu129; declared floors torch>=2.8, torchvision>=0.23 (was torch>=2.0)
- `tensorrt` extra: TensorRT 11 (`tensorrt-cu12>=11.1,<12`, was 10.11+). **Engines serialized with TensorRT 10 must be regenerated**
- `onnxruntime-gpu>=1.26,<1.27` (floor raised from 1.22); `onnxscript>=0.7` added (dynamo exporter requirement)
- Removed unused dependencies `basicsr-fixed` / `onnxconverter-common`

**Also included (additive)**:
- ACES: 4 transfer functions and AP0↔XYZ conversions promoted to public API; ACES modules no longer allocate CUDA memory at import time
- filter: `BORDER_REPLICATE` / `BORDER_REFLECT_101` root exports

**Who should upgrade**: all users — audit call sites covered by the fail-fast validation, keyword renames, and the TensorRT precision contract before upgrading. Pin `pixtreme[all]<0.9.0` if you cannot migrate immediately.

**Upgrade**:
```bash
pip install --upgrade "pixtreme[all]>=0.9.0"
```

### v0.8.5: Float32-Only Architecture Enforcement (2025-10-29)

**🔥 BREAKING CHANGE: All filter functions now strictly require float32 input** - v0.8.5 enforces pixtreme's core design principle that all image processing happens in float32.

**What changed**:
- **Filter functions reject uint8 input**: `bilateral_filter`, `unsharp_mask`, `box_blur`, `gaussian_blur`, `sobel`, `median_blur` now raise `ValueError` if given uint8 arrays
- **Explicit conversion required**: Users must call `to_float32()` before filtering uint8 images
- **No more implicit conversions**: Filters no longer silently convert uint8 → float32

**Why this change**:
- **Design consistency**: pixtreme is fundamentally a float32-based library for GPU processing
- **User control**: Explicit conversions prevent unexpected behavior and give users full control
- **Performance**: Eliminates hidden conversion overhead and potential precision issues

**Migration guide**:
```python
# OLD (v0.8.4 and earlier - implicit conversion)
import cupy as cp
from pixtreme_filter import bilateral_filter

img_uint8 = cp.random.randint(0, 256, (512, 512, 3), dtype=cp.uint8)
result = bilateral_filter(img_uint8, d=5, sigma_color=75, sigma_space=5.0)  # Worked in v0.8.4

# NEW (v0.8.5+ - explicit conversion required)
from pixtreme_core.utils.dtypes import to_float32

img_uint8 = cp.random.randint(0, 256, (512, 512, 3), dtype=cp.uint8)
img_float = to_float32(img_uint8)  # Explicit: uint8 [0-255] → float32 [0-1]
result = bilateral_filter(img_float, d=5, sigma_color=0.2, sigma_space=5.0)  # Note: sigma_color adjusted for [0-1] range
```

**Note**: sigma_color parameter values differ between uint8 and float32:
- uint8 images: typical range 10-150 (for values 0-255)
- float32 images: typical range 0.05-0.5 (for values 0-1)

**New features in v0.8.5**:
- **Bilateral filter**: Edge-preserving smoothing added to pixtreme-filter
  - GPU-accelerated CUDA kernel implementation
  - OpenCV-compatible API and behavior
  - Effective for noise reduction while maintaining sharp edges

**Bug fixes**:
- **Windows cp932 encoding**: Fixed UnicodeEncodeError when printing from `model_convert.py` and `onnx_upscaler.py` on Windows systems
  - Replaced all emoji characters with ASCII equivalents
  - All diagnostic messages now safe for cp932 encoding

**Who should upgrade**:
- **All users upgrading to v0.8.5** - Code changes required for filter functions
- Users wanting bilateral filter or Windows emoji fix can upgrade safely with migration

**Upgrade**:
```bash
pip install --upgrade pixtreme[all]>=0.8.5
```

### v0.8.4: Critical Bugfix for Type Hints (2025-10-27)

**🔥 CRITICAL BUGFIX: Fixed runtime import errors in non-PyTorch environments** - v0.8.3 still had issues with type hint evaluation causing `AttributeError` when PyTorch is not installed.

**What was fixed**:
- **Type hints wrapped in string literals**: All `torch.device` and `torch.Tensor` references in type annotations now use string literals (`"torch.Tensor"`) to prevent runtime evaluation
- **Root cause**: While v0.8.3 added `from __future__ import annotations`, some environments (Python 3.13, pydantic) still evaluate annotations at runtime
- **Impact**: `pixtreme-core` now imports successfully in all environments, regardless of PyTorch installation status

**Who should upgrade**:
- **All v0.8.3 users immediately** - v0.8.3 is broken in non-PyTorch environments
- Users running Python 3.13 or using libraries that evaluate annotations at runtime

**Upgrade**:
```bash
pip install --upgrade pixtreme-core>=0.8.4
# or
pip install --upgrade pixtreme[all]>=0.8.4
```

**Technical details**: Changed type hints from `torch.device` to `"torch.device"` in `dlpack.py:25,26,47,64` to ensure compatibility with all annotation evaluation strategies.

### v0.8.3: nvimgcodec v0.6.0+ Required (2025-10-27)

**⚠️ BREAKING CHANGE: nvimgcodec >= 0.6.0 now required** - v0.8.3 drops support for nvimgcodec v0.5.x to simplify code and adopt the latest API.

**What changed**:
- **Dependency updated**: `nvidia-nvimgcodec-cu12[all]>=0.6.0` (was >=0.5.0)
- **dlpack.py**: Improved `TYPE_CHECKING` pattern for torch imports (fixes community-reported issue)
- **imread.py**: Simplified to use nvimgcodec v0.6.0 API only (removed backward compatibility code)

**nvimgcodec v0.6.0 API Changes**:
- `DecodeSource` class removed from Python API (deprecated in v0.6.0-beta.6)
- Direct file path passing to `Decoder.read()` is the new standard
- Cleaner, simpler API with better performance

**Who should upgrade**:
- **All users** - v0.8.3 requires nvimgcodec >= 0.6.0
- If you need nvimgcodec < 0.6.0, stay on pixtreme v0.8.2

**Upgrade**:
```bash
pip install --upgrade pixtreme-core>=0.8.3
# or
pip install --upgrade pixtreme[all]>=0.8.3
```

**Note**: This will automatically upgrade nvimgcodec to v0.6.0+ due to dependency requirements.

### v0.8.2: Critical Bugfix (2025-10-27)

**Fixed import error when PyTorch not installed** - v0.8.0 had a critical bug where `pixtreme-core` would fail to import in environments without PyTorch.

**What was fixed**:
- Added `from __future__ import annotations` to prevent runtime evaluation of type hints
- `torch.device` type annotations no longer cause `AttributeError` when torch is not installed
- Module imports now succeed with `TORCH_AVAILABLE=False` flag set correctly

**Who should upgrade**:
- **All v0.8.0 users** - v0.8.0 is broken in non-PyTorch environments
- Users who install `pixtreme-core` without the full `pixtreme[all]` bundle

**Upgrade**:
```bash
pip install --upgrade pixtreme-core>=0.8.2
# or
pip install --upgrade pixtreme[all]>=0.8.2
```

### v0.8.0: Morphology Operations Reorganization

**Morphology module moved from core to filter** - The `erode` function and related morphology operations have been relocated to the `pixtreme-filter` package for better organization.

**API Changes**:
- `erode()` moved from `pixtreme-core` to `pixtreme-filter`
- New operations added: `dilate()`, `morphology_open()`, `morphology_close()`, `morphology_gradient()`
- All morphology functions now in unified `pixtreme_filter.morphology` module

**Migration**: Update your imports:
```python
# OLD (v0.7.x and earlier)
from pixtreme_core import erode

# NEW (v0.8.0+)
from pixtreme_filter.morphology import erode, dilate, morphology_open, morphology_close, morphology_gradient

# Or use the convenience import
import pixtreme as px
px.erode(image, ksize=5)  # Still works if pixtreme-filter is installed
```

**Installation**: Ensure `pixtreme-filter` is installed:
```bash
pip install pixtreme[filter]  # or pixtreme[all] for all features
```

### v0.7.3: Type System & Build Modernization

**Python 3.12+ now required** - pixtreme v0.7.3 drops Python 3.10/3.11 support and requires Python 3.12 or later.

**Type System Improvements**:
- Full mypy compatibility with strict type checking
- Improved error messages with detailed value reporting
- 15+ type annotation bugs fixed across core modules

**Build System Optimization**:
- License classifier added to all packages (MIT)
- Issues URL standardized across packages
- Pre-commit hooks for local quality checks (mypy, ruff, version consistency)
- sdist/wheel metadata improvements

**Developer Experience**:
- uv-native pre-commit config (no virtualenv overhead)
- Better error reporting in dtype conversions and validation
- Comprehensive metadata for PyPI display

**Migration**: Update Python to 3.12+ and reinstall:
```bash
# Ensure Python 3.12 or later
python --version  # Should show 3.12.x or 3.13.x

pip install --upgrade pixtreme>=0.7.3
```

### v0.6.3: Bug Fixes and API Restoration

**v0.6.3 restores missing APIs from v0.6.0** and includes important bug fixes:

**Restored APIs** (accidentally removed in v0.6.0):
- I/O functions: `destroy_all_windows()`, `imdecode()`, `imencode()`, `waitkey()`
- Type conversions: `to_dtype()`, `to_float16()`, `to_float64()`
- Transform functions: `affine_transform()`, `get_inverse_matrix()`

**Bug Fixes**:
- `imwrite()` now returns `bool` (success/failure) instead of `None`
- LUT parser improved to skip non-numeric lines in `.cube` files
- Comprehensive test suite added (297 tests, 99.7% pass rate)

**Migration**: If you encountered `AttributeError` for these functions in v0.6.0, upgrade to v0.6.3:
```bash
pip install --upgrade pixtreme>=0.6.3
```

### v0.6.0: Modular Package Structure

**pixtreme is now split into modular packages** for better flexibility:

- `pixtreme-core`: Core functionality (always installed)
- `pixtreme-aces`: ACES color management (optional)
- `pixtreme-filter`: Image filtering (optional)
- `pixtreme-draw`: Drawing primitives (optional)
- `pixtreme-upscale`: Deep learning upscalers (optional)

**Backward compatibility**: `import pixtreme as px` still works with all installed packages.

**Migration**: No code changes needed. `pip install pixtreme[all]` for previous behavior.

## ✨ Features

### 🎯 Image Processing
- **11 Interpolation Methods**: Nearest, Linear, Cubic, Area, Lanczos (2/3/4), Mitchell, B-Spline, Catmull-Rom
- **Advanced Transforms**: Affine transformations, tiling with overlap blending
- **Morphological Operations**: Erosion with custom kernels
- **GPU-Accelerated Filters**: Gaussian blur, custom convolutions

### 🎨 Color Science
- **Color Spaces**: BGR/RGB, HSV, YCbCr, YUV (4:2:0, 4:2:2), Grayscale
- **ACES Pipeline**: Complete Academy Color Encoding System workflow
- **3D LUT Processing**: Trilinear and tetrahedral interpolation
- **10-bit Precision**: Professional video color accuracy

### 🤖 Deep Learning
- **Multi-Backend Support**: ONNX Runtime, PyTorch, TensorRT
- **Super Resolution**: Built-in upscaling with various models
- **Batch Processing**: Efficient multi-image inference
- **Model Optimization**: Automatic conversion and optimization tools

### 🔧 Advanced Features
- **Memory I/O**: Encode/decode images in memory
- **Hardware Acceleration**: NVIDIA nvimgcodec support
- **Drawing Tools**: GPU-accelerated shapes and text rendering
- **Framework Integration**: Zero-copy tensor sharing via DLPack

## 🚀 Installation

### Requirements
- Python >= 3.12
- CUDA Toolkit 12.x
- NVIDIA GPU with compute capability >= 6.0

### Quick Install

**v0.6.0 introduces modular packages** - install only what you need:

```bash
# Core only (I/O, color, transform, utils)
pip install pixtreme

# Core + ACES color management
pip install pixtreme[aces]

# Core + image filters
pip install pixtreme[filter]

# Core + drawing primitives
pip install pixtreme[draw]

# Core + deep learning upscalers
pip install pixtreme[upscale]

# All features
pip install pixtreme[all]

```

### Individual Packages

You can also install packages individually:

```bash
pip install pixtreme-core      # Core functionality
pip install pixtreme-aces      # ACES color management
pip install pixtreme-filter    # Image filtering
pip install pixtreme-draw      # Drawing primitives
pip install pixtreme-upscale   # Deep learning upscalers
```

### Development Setup

```bash
# Clone the repository
git clone https://github.com/sync-dev-org/pixtreme.git
cd pixtreme

# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup development environment
uv python pin 3.12
uv sync --extra dev --extra opencv
```

## 💡 Quick Start

```python
import pixtreme as px

# Read image directly to GPU as float32 (BGR format)
image = px.imread("photo.jpg")

# All operations work on GPU memory
image_rgb = px.bgr_to_rgb(image)
image_hsv = px.rgb_to_hsv(image_rgb)

# High-quality resize with 11 interpolation methods
image = px.resize(image, (1920, 1080), interpolation=px.INTER_LANCZOS4)

# Choose backend based on your needs
upscaler = px.OnnxUpscaler("models/realesrgan.onnx")     # Balanced
# upscaler = px.TrtUpscaler("models/realesrgan.trt")     # Fastest
# upscaler = px.TorchUpscaler("models/realesrgan.pth")   # Most flexible

# Upscale with single method call
upscaled = upscaler.get(image)

# Professional color grading with 3D LUT
lut = px.read_lut("cinematic_look.cube")
graded = px.apply_lut(image, lut, interpolation=1)  # Tetrahedral

# Save with format-specific options
px.imwrite("output.jpg", graded, params=[px.IMWRITE_JPEG_QUALITY, 95])
```

## 📖 API Reference

The meta-package exposes a flat namespace: use `pixtreme.imread`, `pixtreme.resize`, and similar names directly. Names such as `pixtreme.color`, `pixtreme.filter`, and `pixtreme.upscale` are not namespace modules.

The tables below list every public function and class exported by the installed core, ACES, filter, draw, and upscale components. The **Parameter names** column is intentionally machine-readable: it contains the exact names in runtime signature order, while types and defaults remain available through Python introspection.

### Selector and behavior contracts

- Image dtype selectors use the canonical NumPy spellings `uint8`, `uint16`, `float16`, `float32`, and `float64`. The aliases `fp16`, `fp32`, and `fp64` are accepted at the normalization boundary. `imread` and `imdecode` support `uint8`, `uint16`, `float16`, and `float32`; `to_dtype` also supports `float64`. Unknown tokens raise `ValueError`.
- DLPack interoperability is limited to NumPy, CuPy, PyTorch, and `nvimgcodec.Image`.
- Strict filter APIs reject non-`float32` images with `ValueError` and direct callers to `to_float32()`: `bilateral_filter`, `box_blur`, `box_filter`, `canny`, `clahe`, `corner_harris`, `dog`, `equalize_hist`, `GaussianBlur.get`, `gaussian_blur`, `laplacian`, `match_template`, `median_blur`, `sobel`, `unsharp_mask`, and `white_balance`.
- Converting filter APIs accept supported image dtypes and return `float32`: `dilate`, `erode`, `morphology_blackhat`, `morphology_close`, `morphology_gradient`, `morphology_open`, and `morphology_tophat`.
- `BORDER_REPLICATE` and `BORDER_REFLECT_101` are the supported public border selectors for filter APIs that expose `border_type`.
- `check_torch_model`, `check_onnx_model`, and `check_trt_model` validate by returning `None` on success and raising on failure; they are not boolean predicates.
- TensorRT conversion uses `precision="fp32"` or `precision="tf32"`. Build an engine explicitly with an `onnx_to_trt*` function before loading it with `TrtUpscaler`.

### Core API (`pixtreme-core`)

| API | Parameter names | Returns | Description |
|---|---|---|---|
| `destroy_all_windows` | - | `None` | Destroy all windows. |
| `imdecode` | `src, dtype` | `cupy.ndarray` | Decode an image from a bytes object into a CuPy array. |
| `imencode` | `image, ext, params` | `bytes` | Encode an image to bytes from a CuPy array. |
| `imread` | `input_path, dtype` | `cupy.ndarray` | Read an image from a file into a CuPy array. |
| `imshow` | `title, image, scale, is_rgb` | `None` | Image show function for numpy and cupy arrays. in RGB format. |
| `imwrite` | `output_path, image, params` | `bool` | Write an image to a file. |
| `waitkey` | `delay` | `int` | Wait for a pressed key. |
| `Device` | `device_id` | `Device` instance | Context manager for CUDA device selection. |
| `to_cupy` | `image` | `cupy.ndarray` | Convert a NumPy, CuPy, PyTorch, or nvimgcodec image to CuPy. |
| `to_numpy` | `image` | `numpy.ndarray` | Convert a NumPy, CuPy, PyTorch, or nvimgcodec image to NumPy. |
| `to_tensor` | `image, device` | `torch.Tensor` | Convert a NumPy, CuPy, or nvimgcodec image to PyTorch. |
| `to_dtype` | `image, dtype` | `numpy.ndarray or cupy.ndarray` | Convert an image using the canonical dtype selector vocabulary. |
| `to_float16` | `image` | `numpy.ndarray or cupy.ndarray` | Call `to_float16`. |
| `to_float32` | `image, clip` | `numpy.ndarray or cupy.ndarray` | Call `to_float32`. |
| `to_float64` | `image` | `numpy.ndarray or cupy.ndarray` | Call `to_float64`. |
| `to_uint16` | `image` | `numpy.ndarray or cupy.ndarray` | Call `to_uint16`. |
| `to_uint8` | `image` | `numpy.ndarray or cupy.ndarray` | Call `to_uint8`. |
| `apply_lut` | `image, lut, interpolation` | `cupy.ndarray` | Apply a 3D LUT to an image with trilinear interpolation. |
| `read_lut` | `file_path, use_cache` | `cupy.ndarray` | Read a 3D LUT Cube file and return the LUT data as a CuPy ndarray. |
| `bgr_to_rgb` | `image` | `numpy.ndarray or cupy.ndarray` | Convert BGR to RGB |
| `rgb_to_bgr` | `image` | `numpy.ndarray or cupy.ndarray` | Convert RGB to BGR |
| `bgr_to_grayscale` | `image` | `cupy.ndarray` | Convert BGR to Grayscale |
| `rgb_to_grayscale` | `image` | `cupy.ndarray` | Convert RGB to Grayscale |
| `bgr_to_hsv` | `image` | `cupy.ndarray` | Convert BGR to HSV |
| `hsv_to_bgr` | `image` | `cupy.ndarray` | Convert HSV to BGR |
| `hsv_to_rgb` | `image` | `cupy.ndarray` | Convert HSV to RGB |
| `rgb_to_hsv` | `image` | `cupy.ndarray` | Convert RGB to HSV |
| `bgr_to_ycbcr` | `image` | `cupy.ndarray` | Call `bgr_to_ycbcr`. |
| `rgb_to_ycbcr` | `image` | `cupy.ndarray` | Convert RGB to YCbCr |
| `ycbcr_full_to_legal` | `image` | `cupy.ndarray` | Convert YCbCr full-range to legal-range |
| `ycbcr_legal_to_full` | `image` | `cupy.ndarray` | Convert YCbCr legal-range to full-range |
| `ycbcr_to_bgr` | `image` | `cupy.ndarray` | Call `ycbcr_to_bgr`. |
| `ycbcr_to_grayscale` | `image` | `cupy.ndarray` | YCbCr to Grayscale conversion |
| `ycbcr_to_rgb` | `image` | `cupy.ndarray` | Convert YCbCr to RGB |
| `uyvy422_to_ycbcr444` | `uyvy_data, width, height` | `cupy.ndarray` | Convert UYVY422 to YCbCr444. |
| `ndi_uyvy422_to_ycbcr444` | `uyvy_data, use_bilinear` | `cupy.ndarray` | Convert NDI UYVY422 to YCbCr444 using CUDA kernel. |
| `yuv420p_to_ycbcr444` | `yuv420_data, width, height, interpolation` | `cupy.ndarray` | Convert YUV 4:2:0 to YCbCr 4:4:4 |
| `yuv422p10le_to_ycbcr444` | `ycbcr422_data, width, height` | `cupy.ndarray` | Convert YCbCr 4:2:2 to YCbCr 4:4:4 |
| `affine` | `image, M, dsize, flags` | `cupy.ndarray` | Apply an affine transformation to the input image. Using CUDA. |
| `affine_transform` | `image, M, dsize, flags` | `cupy.ndarray` | Apply an affine transformation to the input image. Using CUDA. |
| `add_padding` | `image, patch_size, overlap` | `cupy.ndarray` | Call `add_padding`. |
| `create_gaussian_weights` | `size, sigma` | `cupy.ndarray` | Create a Gaussian weight map for tile blending. |
| `get_inverse_matrix` | `M` | `cupy.ndarray or numpy.ndarray` | Get the inverse of the affine matrix. |
| `merge_tiles` | `tiles, original_shape, padded_shape, scale, tile_size, overlap` | `cupy.ndarray` | Call `merge_tiles`. |
| `resize` | `image, dsize, fx, fy, interpolation` | `cupy.ndarray` | Resize the input image to the specified size. |
| `stack_images` | `images, axis` | `cupy.ndarray` | Stack a list of images along a specified axis. |
| `subsample_image` | `image, dim` | `list[cupy.ndarray]` | Perform interleaved subsampling of an image without for loops. |
| `subsample_image_back` | `subsampled_images, dim` | `cupy.ndarray` | Ultra-optimized reconstruction using single-pass kernel. |
| `tile_image` | `image, tile_size, overlap` | `tuple[list[cupy.ndarray], tuple[int, int, int]]` | Split the input image into overlapping tiles. |

### ACES API (`pixtreme-aces`)

| API | Parameter names | Returns | Description |
|---|---|---|---|
| `rec709_to_aces2065_1` | `image` | `cupy.ndarray or numpy.ndarray` | Convert Rec.709 to ACES2065-1 using ACES 1.2 IDT. |
| `aces2065_1_to_rec709` | `image` | `cupy.ndarray or numpy.ndarray` | Convert ACES2065-1 to Rec.709 using ACES 1.2 ODT. |
| `aces2065_1_to_acescct` | `image` | `cupy.ndarray or numpy.ndarray` | Convert ACES2065-1 (AP0) to ACEScct (AP1 log-encoded). |
| `acescct_to_aces2065_1` | `image` | `cupy.ndarray or numpy.ndarray` | Convert ACEScct (AP1 log-encoded) to ACES2065-1 (AP0). |
| `aces2065_1_to_acescg` | `image` | `cupy.ndarray or numpy.ndarray` | Convert ACES2065-1 (AP0) to ACEScg (AP1 linear). |
| `acescg_to_aces2065_1` | `image` | `cupy.ndarray or numpy.ndarray` | Convert ACEScg (AP1 linear) to ACES2065-1 (AP0). |
| `srgb_eotf` | `image` | `cupy.ndarray or numpy.ndarray` | sRGB EOTF (Electro-Optical Transfer Function). |
| `srgb_inverse_eotf` | `image` | `cupy.ndarray or numpy.ndarray` | sRGB Inverse EOTF (= sRGB OETF). |
| `bt1886_eotf` | `image, L_w, L_b` | `cupy.ndarray or numpy.ndarray` | BT.1886 EOTF (Rec.709 reference display). |
| `bt1886_inverse_eotf` | `image, L_w, L_b` | `cupy.ndarray or numpy.ndarray` | BT.1886 Inverse EOTF (= BT.1886 OETF). |
| `xyz_d60_to_ap0` | `image` | `cupy.ndarray or numpy.ndarray` | Convert CIE XYZ (D60) to ACES AP0 (ACES2065-1). |
| `ap0_to_xyz_d60` | `image` | `cupy.ndarray or numpy.ndarray` | Convert ACES AP0 (ACES2065-1) to CIE XYZ (D60). |

### Filter API (`pixtreme-filter`)

| API | Parameter names | Returns | Description |
|---|---|---|---|
| `bilateral_filter` | `image, d, sigma_color, sigma_space` | `cupy.ndarray` | Apply bilateral filter to an image. |
| `box_blur` | `image, ksize` | `cupy.ndarray` | Apply box blur (mean filter) to an image. |
| `box_filter` | `image, ksize, normalize, border_type` | `cupy.ndarray` | Apply box filter to a grayscale image. |
| `canny` | `image, threshold1, threshold2, aperture_size, l2_gradient` | `cupy.ndarray` | Apply Canny edge detection algorithm. |
| `clahe` | `image, clip_limit, tile_grid_size` | `cupy.ndarray` | Apply CLAHE (Contrast Limited Adaptive Histogram Equalization). |
| `corner_harris` | `image, block_size, ksize, k` | `cupy.ndarray` | Detect corners using Harris corner detection algorithm. |
| `dog` | `image, sigma1, sigma2, ksize1, ksize2` | `cupy.ndarray` | Apply Difference of Gaussians (DoG) filter. |
| `GaussianBlur` | - | `GaussianBlur` instance | Stateless Gaussian filter; call `get(image, ksize, sigma, kernel=None)`. |
| `gaussian_blur` | `image, ksize, sigma, kernel` | `cupy.ndarray` | Apply Gaussian blur to RGB image using CuPy's RawKernel |
| `get_gaussian_kernel` | `ksize, sigma` | `cupy.ndarray` | Generate 1D Gaussian kernel |
| `erode` | `image, ksize, kernel, border_value` | `cupy.ndarray` | Perform GPU-based erosion processing on RGB images |
| `create_erode_kernel` | `ksize` | `cupy.ndarray` | Create kernel for erosion processing |
| `dilate` | `image, ksize, kernel, border_value` | `cupy.ndarray` | Perform GPU-based dilation processing on RGB images |
| `create_dilate_kernel` | `ksize` | `cupy.ndarray` | Create kernel for dilation processing |
| `equalize_hist` | `image, num_bins` | `cupy.ndarray` | Apply histogram equalization to improve image contrast. |
| `laplacian` | `image, ksize` | `cupy.ndarray` | Apply Laplacian filter for edge detection. |
| `match_template` | `image, template, method` | `cupy.ndarray` | Search for a template within an image using various matching methods. |
| `median_blur` | `image, ksize` | `cupy.ndarray` | Apply median blur filter to an image. |
| `morphology_blackhat` | `image, ksize, kernel` | `cupy.ndarray` | Morphological black hat (closing minus image) |
| `morphology_close` | `image, ksize, kernel` | `cupy.ndarray` | Morphological closing (dilation followed by erosion) |
| `morphology_gradient` | `image, ksize, kernel` | `cupy.ndarray` | Morphological gradient (dilation minus erosion) |
| `morphology_open` | `image, ksize, kernel` | `cupy.ndarray` | Morphological opening (erosion followed by dilation) |
| `morphology_tophat` | `image, ksize, kernel` | `cupy.ndarray` | Morphological top hat (image minus opening) |
| `sobel` | `image, dx, dy, ksize, border_type` | `cupy.ndarray` | Apply Sobel edge detection filter to an image. |
| `unsharp_mask` | `image, sigma, amount, threshold` | `cupy.ndarray` | Apply unsharp mask filter to sharpen an image. |
| `white_balance` | `image, method` | `cupy.ndarray` | Apply white balance color correction to remove color casts. |

### Drawing API (`pixtreme-draw`)

| API | Parameter names | Returns | Description |
|---|---|---|---|
| `create_rounded_mask` | `dsize, mask_offsets, radius_ratio, density, blur_size, sigma` | `cupy.ndarray` | Create a rounded rectangle mask with anti-aliasing and optional blurring. |
| `circle` | `image, center_x, center_y, radius, color` | `cupy.ndarray` | Draw a circle on the image using CuPy. |
| `rectangle` | `image, top_left_x, top_left_y, bottom_right_x, bottom_right_y, color` | `cupy.ndarray` | Draw a rectangle on the image using CuPy. |
| `add_label` | `image, text, org, font_face, font_scale, color, thickness, line_type, label_size, label_color, label_align, density` | `cupy.ndarray` | Add a label to an image. |
| `put_text` | `image, text, org, font_face, font_scale, color, thickness, line_type, density` | `cupy.ndarray` | Draw text on an image. |

### Upscaling and model API (`pixtreme-upscale`)

| API | Parameter names | Returns | Description |
|---|---|---|---|
| `OnnxUpscaler` | `model_path, model_bytes, device_id, provider_options` | `OnnxUpscaler` instance | Load an ONNX model and upscale with `get(image)`. |
| `TorchUpscaler` | `model_path, model_bytes, device, allow_unsafe_checkpoint` | `TorchUpscaler` instance | Load a trusted PyTorch model and upscale with `get(image)`. |
| `TrtUpscaler` | `model_path, model_bytes, device_id` | `TrtUpscaler` instance | Load a trusted TensorRT engine and upscale with `get(image)`. |
| `guess_image_layout` | `image` | `Layout` | Infer the layout of an image array. |
| `check_onnx_model` | `model_path` | `None` | Return `None` when valid; raise when validation fails. |
| `check_torch_model` | `model_path` | `None` | Return `None` when valid; raise when validation fails. |
| `check_trt_model` | `engine_path, verbose` | `None` | Return `None` when valid; raise when validation fails. |
| `onnx_to_onnx_dynamic` | `input_path, output_path, irver` | `None` | Rewrite batch dimensions while preserving the opset-20 pipeline contract. |
| `onnx_to_trt` | `onnx_path, engine_path, input_shape, precision, workspace, spatial_range, batch_range` | `None` | Convert ONNX model to TensorRT engine with automatic dynamic/fixed shape handling. |
| `onnx_to_trt_dynamic_shape` | `onnx_path, engine_path, precision, workspace, batch_range, spatial_range, verbose` | `None` | Build a TensorRT engine with one dynamic optimization profile. |
| `onnx_to_trt_fixed_shape` | `onnx_path, engine_path, input_shape, precision, workspace` | `None` | Convert ONNX model to TensorRT engine with fixed input shape. |
| `torch_to_onnx` | `model_path, onnx_path, input_shape, dynamic_shapes, precision, device` | `None` | Export a Spandrel-loaded PyTorch model through the dynamo pipeline. |

### Constants and public types

Large constant families are grouped rather than listed as individual API rows.

| Group | Count | Representative symbols | Defined by |
|---|---:|---|---|
| Interpolation constants | 11 | `INTER_NEAREST`, `INTER_LINEAR`, `INTER_LANCZOS4` | pixtreme-core |
| Image writing constants | 47 | `IMWRITE_JPEG_QUALITY`, `IMWRITE_PNG_COMPRESSION`, `IMWRITE_EXR_TYPE` | pixtreme-core |
| Template matching constants | 6 | `TM_SQDIFF`, `TM_CCORR_NORMED`, `TM_CCOEFF_NORMED` | pixtreme-filter |
| Border constants | 2 | `BORDER_REPLICATE`, `BORDER_REFLECT_101` | pixtreme-filter |
| Public type aliases | 2 | `DType`, `Layout` | pixtreme-core, pixtreme-upscale |
| Version metadata | 1 | `__version__` | pixtreme |
## Performance Notes

- All color conversion operations use optimized CUDA kernels
- Supports both legal range (16-235) and full range (0-255) for video processing
- 10-bit precision support for professional video workflows
- Zero-copy tensor sharing via DLPack for framework interoperability
- Batch processing support for multiple images

## License

pixtreme is distributed under the MIT License (see [LICENSE](LICENSE)).

## Authors

minamik (@minamikik)

## Acknowledgments

sync.dev
