Skip to content

Add optional OpenCV image decoding and JPEG/PNG encoding - #13

Merged
MilkClouds merged 2 commits into
mainfrom
feat/opencv-image-codecs
Oct 2, 2026
Merged

MilkClouds merged 2 commits into
mainfrom
feat/opencv-image-codecs

Conversation

@MilkClouds

@MilkClouds MilkClouds commented Oct 2, 2026 •

Copy link
Copy Markdown
Collaborator

Image support reuses an installed OpenCV build without adding native image builds, vendored sources or a second codec backend. This replaces #12; native video/audio code is unchanged.

  • Add CPU decode_image/jpeg/png/webp/gif/avif, NumPy CHW/NCHW output, orientation and animation handling, plus JpegEncoder and PngEncoder.
  • Import OpenCV lazily; reuse cv2 >= 4.13 or install the optional images extra. NumPy remains the only required Python dependency. Pillow is test-only.
  • HEIC is explicitly unsupported: no ctypes/libheif binding, system-library setup or binary fixtures. APNG, high-bit-depth AVIF, CMYK JPEG UNCHANGED and nondefault per-call AVIF thread settings also raise explicit errors. AVIF alpha removal follows OpenCV's straight-RGB behavior, documented as a difference from TorchCodec.
  • Keep input/mode validation, color conversion and orientation handling required to adapt OpenCV to the public API. Image runtime implementation is approximately 544 Python lines, plus decoder exports. Include source-generated tests and a 65-line corpus benchmark.

Validation: Ruff lint/format passed; full local pytest --compare: 444 passed, including a regression for 1/2/4-bit grayscale PNG transparency. Tests cover independent encoder output decoding, color/depth/layout, all-frame animation, orientation, failures and lazy optional imports.

The final adapter matched TorchCodec 0.17.0 exactly for RGB output on 54 JPEG/PNG/WebP inputs. Single-CPU geometric-mean latency ratios vs TorchCodec: JPEG 1.02–1.05×, PNG 1.28×, WebP 1.07–1.11×. These are corpus-specific results; encoding speed was not benchmarked. Details and limitations: docs/images.md.

@MilkClouds
MilkClouds merged commit 125a515 into main Oct 2, 2026
2 checks passed
@MilkClouds
MilkClouds deleted the feat/opencv-image-codecs branch October 2, 2026 11:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant