edgefirst-codec

JPEG and PNG decoding straight into pre-allocated tensors — no per-frame allocations, with optional hardware acceleration on Linux.

PyPI License

Part of the EdgeFirst HAL

edgefirst-codec is one of five Python packages built from the EdgeFirst Hardware Abstraction Layer.

The EdgeFirstAI/hal repository is the home for all of them — source, issue tracker, architecture documentation and release notes.

Package Provides
edgefirst-tensor Zero-copy tensor allocation and host/GPU/CUDA mapping
edgefirst-codec JPEG and PNG decoding directly into pre-allocated tensors (this package)
edgefirst-image GPU-accelerated colour conversion, resize, letterbox, tiling and drawing
edgefirst-decoder YOLO and ModelPack output decoding
edgefirst-tracker ByteTrack multi-object tracking

Installation

pip install edgefirst-codec

Requires Python 3.8 or newer; edgefirst-tensor and NumPy are installed automatically. Wheels are published for Linux (x86_64, aarch64), macOS (arm64), and Windows (x86_64), and are self-contained — there is no system JPEG library to install.

Packages install under the PEP 420 edgefirst.* namespace, so the import is edgefirst.codec.

Quick start

For maximum performance, decode straight into a tensor allocated by edgefirst.image's ImageProcessor.create_image() — DMA/PBO-backed and GPU-pitch-aligned — then hand it to ImageProcessor.convert() for colour conversion and resize. decode_file_into / decode_into are free functions rather than Tensor methods precisely so they can take a tensor from another edgefirst.* package:

import numpy as np
from edgefirst.codec import Tensor, decode_file_into
from edgefirst.image import Flip, ImageProcessor, PixelFormat, Rotation

processor = ImageProcessor()

# peek_image_info_file reads the header only — no pixels are decoded.
info = Tensor.peek_image_info_file("frame.jpg")
print(info.width, info.height, info.format)  # e.g. 1280 720 PixelFormat.Nv16

# Allocate once, outside the loop. The decoder reconfigures the tensor's
# dimensions and format within this allocation, so one tensor sized for the
# largest expected frame can receive smaller images without reallocating.
src = processor.create_image(
    info.width, info.height, PixelFormat.Nv12, "uint8", "readwrite"
)
dst = processor.create_image(640, 640, PixelFormat.Rgb, "uint8", "readwrite")

info = decode_file_into(src, "frame.jpg")  # or decode_into(src, jpeg_bytes)
# convert() performs colour conversion (native → RGB) and resize; the codec
# reports EXIF orientation in `info` but does not apply it, so pass it on.
rotation = Rotation.degrees_clockwise(info.rotation_degrees)
flip = Flip.Horizontal if info.flip_horizontal else Flip.NoFlip
processor.convert(src, dst, rotation, flip)

with dst.map() as view:
    data = np.frombuffer(view, dtype=np.uint8)

Same-package pipelines that never leave edgefirst.codec can use the equivalent Tensor.decode_image_file() method instead — tensor.decode_image_file("frame.jpg") — but decode_image_file is a method, and its self must literally be an edgefirst.codec.Tensor; a DMA/PBO-backed destination from edgefirst.image.ImageProcessor.create_image() is a different package's type and can never be that self, so it must go through the free functions decode_into / decode_file_into instead.

Images decode in their native pixel format and are never colour-converted, rotated or resized. A colour JPEG lands on the NV format matching its own chroma sampling (4:2:0 → Nv12, 4:2:2 → Nv16, 4:4:4 → Nv24), greyscale on Grey, and PNG on Rgb / Rgba / Grey. Nothing is resampled on the way out.

EXIF orientation is reported, never applied: info.rotation_degrees and info.flip_horizontal carry the transform your pipeline should apply downstream, and the reported dimensions are unrotated.

Tuning the decode

from edgefirst.codec import DctMethod, PixelFormat, set_dct_method, set_output_format

set_dct_method(DctMethod.Fast)  # faster IDCT, small bounded accuracy cost
set_output_format(PixelFormat.Rgb)  # fused colour conversion inside the decode

Both settings are thread-local — apply them on every thread that decodes. set_output_format fuses colour conversion into the decode's MCU write stage, which is a pure-CPU single-pass path; pass None to restore native output.

PixelFormat and the other value types (TensorMemory, Region, the colour axis enums) are accepted from any edgefirst.* package, not just this one — they compare and hash equal across packages by value, so ==, dict keys and set membership all work regardless of which package's copy you pass. Tensors, Decoder and ProtoData cross packages too, through the capsule protocols. Importing PixelFormat from edgefirst.codec when calling into this package is still good style for readability, not a requirement. See the Interoperability section below for the one thing that does not cross: isinstance against a concrete class.

What this package provides

API Purpose
Tensor.peek_image_info() / peek_image_info_file() Read dimensions, format and EXIF orientation from the header alone
Tensor.decode_image() / decode_image_file() Decode into a pre-allocated edgefirst.codec.Tensor
decode_into() / decode_file_into() Decode into a tensor from any edgefirst.* package (e.g. edgefirst.image.ImageProcessor.create_image())
ImageInfo Decoded dimensions, native format, row stride, EXIF orientation
set_dct_method() / DctMethod IDCT accuracy/speed selection
set_output_format() Fused Rgb / Nv12 decode output
is_v4l2_available() Whether a V4L2 hardware JPEG decoder is present

Hardware acceleration

On Linux the decoder transparently tries hardware backends before the software path and falls back without any API change:

  • V4L2 mem2mem — SoC JPEG blocks such as the i.MX mxc-jpeg. Discovery is capability-based, with no hardcoded device node. Opt out with EDGEFIRST_DISABLE_V4L2=1.
  • nvJPEG — CUDA GPU decode on NVIDIA platforms such as Jetson Orin. Loaded via dlopen, so there is no link-time CUDA dependency. Opt in with EDGEFIRST_ENABLE_NVJPEG=1.

Footprint

Adding edgefirst-codec to a project costs roughly 1.5 MB of downloads (this package plus edgefirst-tensor), excluding NumPy. That is roughly an order of magnitude smaller than Pillow or OpenCV, and a few times larger than a bare libjpeg-turbo binding — while bundling PNG, EXIF and the hardware backends, with no system libraries to install. See the Rust crate README for the comparison table.

Supported inputs

JPEG decoding covers baseline DCT, 8-bit precision, 1 or 3 components. Progressive, lossless, hierarchical and arithmetic-coded JPEG, CMYK/YCCK and non-8-bit precision are rejected with a typed error rather than mis-decoded. PNG goes through zune-png and supports 8-bit and 16-bit Luma / LumaA / RGB / RGBA. The Rust crate README documents the full matrix.

Interoperability

decode_into / decode_file_into accept a tensor from any edgefirst.* package because each extension module registers its own Tensor type object (PyO3 issue #1444 — isinstance across packages is always False, even for two objects wrapping the same Rust type). Acceptance goes through the __edgefirst_tensor__ capsule protocol every Tensor implements:

# CORRECT — works regardless of which edgefirst.* package produced obj
if hasattr(obj, "__edgefirst_tensor__"):
    ...

# WRONG — always False for a tensor from a sibling package
if isinstance(obj, edgefirst.image.Tensor):
    ...

edgefirst.tensor.EdgeFirstTensorExportable (re-exported here as edgefirst.codec.EdgeFirstTensorExportable) is a typing.Protocol you can annotate a cross-package parameter with. See crates/python-common/INTEROP.md for the full protocol.

Versioning and changelog

All four edgefirst-* packages are versioned and released together with the HAL itself, so a given version number refers to the same source tree in every language. Because of that there is no per-package changelog: release notes for every version live in the single CHANGELOG.md in the hal repository, which follows Keep a Changelog and Semantic Versioning.

Links

License

Apache-2.0

Project links

Data verified by PyPI on Sep 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.30.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for au-zone from gravatar.com au-zone

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Au-Zone Technologies

GitHub Statistics

Data verified by PyPI on Sep 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.8

Tags

jpeg png image-decoding zero-copy edge-ai

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

edgefirst_codec-0.29.4-cp311-abi3-win_amd64.whl (651.9 kB view details)

Uploaded CPython 3.11+Windows x86-64

edgefirst_codec-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (806.8 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ x86-64

edgefirst_codec-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (782.7 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

edgefirst_codec-0.29.4-cp311-abi3-macosx_11_0_arm64.whl (705.5 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

edgefirst_codec-0.29.4-cp38-abi3-win_amd64.whl (657.8 kB view details)

Uploaded CPython 3.8+Windows x86-64

edgefirst_codec-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (809.7 kB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ x86-64

edgefirst_codec-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (786.5 kB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ ARM64

edgefirst_codec-0.29.4-cp38-abi3-macosx_11_0_arm64.whl (712.1 kB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

File details

Details for the file edgefirst_codec-0.29.4-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_codec-0.29.4-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 52be1c0ec46fc5e36a7e36c37dc18cc39808fe909c5aab89de62aa648e0250c7
MD5 952d63dac47e85e48707cf510651a034
BLAKE2b-256 381aaedacd18f73b8863fc9c008e5b2ce5c2a155f3f2c302dc2be8570524db9e

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_codec-0.29.4-cp311-abi3-win_amd64.whl:

Publisher: release.yml on EdgeFirstAI/hal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file edgefirst_codec-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for edgefirst_codec-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 be27d1df5912636173f981452b2efe29bc7a080aa396d9e9e12895ede2ac426c
MD5 3872172f89a6905f128cc92e2bc336f6
BLAKE2b-256 06ded1380eca67091464d51e6bf2ef63fff9b2f7e2ea44838186f21a5bebe704

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_codec-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on EdgeFirstAI/hal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file edgefirst_codec-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_codec-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ab33cc10c8d1454dc2a07d2dc55600ada518e0605c7693626919767c3c113b65
MD5 efc0282af9de8aef57873439099d79ef
BLAKE2b-256 794e3637b0b2f73b6e671a6c4524672655272b91de6e474d71db1f37165e0151

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_codec-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on EdgeFirstAI/hal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file edgefirst_codec-0.29.4-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_codec-0.29.4-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d6576f12ec8a54cd49b7b01072d59d7a1ffe2e5edf3051b1504f9f2da0bfa5ad
MD5 a231ba31dc0ad81707297bc92bf0c9d7
BLAKE2b-256 2c314b9cfa7b513b19492ae988c196d2d69e6c447585fd7ce03f2bbe49b87ac8

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_codec-0.29.4-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on EdgeFirstAI/hal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file edgefirst_codec-0.29.4-cp38-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_codec-0.29.4-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 b6b8bfce5b66d7294a27f6d3f15578873557277a5c471698e3d24ac6b1e6cc66
MD5 d9b1116276f1411684bf72483bc0c7ea
BLAKE2b-256 dff92250891bb928af1d3eb536ad72d7f4f97c0106d3a06c46b67dfbaf0505ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_codec-0.29.4-cp38-abi3-win_amd64.whl:

Publisher: release.yml on EdgeFirstAI/hal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file edgefirst_codec-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for edgefirst_codec-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 608b6cd42b51e9c02986173d48eb5e91d9619d1bfd59743851c1e1defbfd9a67
MD5 862252272a3c486bdb2b6df96fc817b5
BLAKE2b-256 221fac88baf06599314946b9c46eef4cfb47282f41b96070aa393cc1371adfe7

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_codec-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on EdgeFirstAI/hal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file edgefirst_codec-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_codec-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e5ad5a2131ac9c5087129cf2eb33389746a8a4a0c8c0c8b125f256f1a77a9776
MD5 bdaa1a7722daecf96ce479f219feab08
BLAKE2b-256 0eb9a8609896496ccad96d8845b0aeb74deb2c1567b1f53e54cab2d5d4dd5081

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_codec-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on EdgeFirstAI/hal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file edgefirst_codec-0.29.4-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_codec-0.29.4-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 dce95b604d573b701680eeaa076939968a41d1c2666810c55eb8981d2cfcfeee
MD5 8ccbc594276114da01d75d13ccde9bbc
BLAKE2b-256 b7c0c0880be161ef336206d2d6a3f11714251bb8b97934d6bad4507a19e40d4b

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_codec-0.29.4-cp38-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on EdgeFirstAI/hal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.30.0

8 files

This release

0.29.4 This release

8 files

0.29.3

8 files

Pre-release

0.29.0rc1

1 file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page