pixtreme 0.9.0

pixtreme: A High-Performance Graphics Library with CUDA Support

🚀 pixtreme

Blazing-fast GPU-accelerated image processing for Python

🌟 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
• Features
• Installation
• Quick Start
• API Reference
• Performance Notes
• 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:

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:

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

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:

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:

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:

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:

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

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:

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

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:

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

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

# 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

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

Authors

minamik (@minamikik)

Acknowledgments

sync.dev