edgefirst-image

GPU-accelerated image preprocessing for edge AI — colour conversion, resize, letterbox, rotation, tiled inference and annotation drawing, in one call per frame.

PyPI License

Part of the EdgeFirst HAL

edgefirst-image 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
edgefirst-image GPU-accelerated colour conversion, resize, letterbox, tiling and drawing (this package)
edgefirst-decoder YOLO and ModelPack output decoding
edgefirst-tracker ByteTrack multi-object tracking

Installation

pip install edgefirst-image

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). This package does not depend on edgefirst-decoder.

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

A single OpenGL ES engine backs this package on every platform — Linux via native EGL and DMA-BUF, macOS and iOS via ANGLE over Metal and IOSurface, Android via native EGL and AHardwareBuffer, Windows via ANGLE over Direct3D 11 and D3D11 textures (PBO remains the fallback where a format has no texture layout) — alongside NXP G2D on i.MX and a portable CPU fallback everywhere else. Backend selection is automatic; no code changes are needed to move between them. The Windows wheel bundles ANGLE's libEGL.dll and libGLESv2.dll next to the extension module, so no setup is required there; EDGEFIRST_D3D11_ADAPTER (alias EDGEFIRST_ANGLE_ADAPTER, and the D3D11 name wins if both are set and differ) picks the GPU on multi-adapter machines.

Quick start

Preprocess a frame into a model input tensor. convert() performs colour conversion, resize, letterboxing, rotation and cropping in a single GPU pass:

import numpy as np
from edgefirst.image import ImageProcessor, PixelFormat

processor = ImageProcessor()

# Allocate once, outside the loop.
src = processor.create_image(1280, 720, PixelFormat.Rgb, "uint8", "readwrite")
model_input = processor.create_image(640, 640, PixelFormat.Rgb, "uint8", "readwrite")

# Fill `src` from your capture source.
with src.map() as view:
    np.frombuffer(view, dtype=np.uint8)[:] = 200

# Omit letterbox= to stretch instead of preserving aspect ratio.
processor.convert(src, model_input, letterbox=[114, 114, 114, 255])

with model_input.map() as view:
    frame = np.frombuffer(view, dtype=np.uint8).reshape(640, 640, 3)

Use create_image() rather than allocating tensors yourself: it supplies DMA-BUF or PBO backing for zero-copy GPU import and GPU pitch alignment, which the plain allocator cannot guarantee.

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.image 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
ImageProcessor The engine; owns the GPU context and caches
create_image() Allocate a GPU-backed, pitch-aligned image tensor
convert() Colour conversion, resize, letterbox, rotation, crop in one pass
Normalization, ColorMode Model input scaling and channel order
Flip, Rotation, Fit Geometry controls
TilingConfig, TileSpec, tile_grid() Tiled (SAHI) inference layout. Merge (TiledFrameAccumulator, lift_tile_boxes) lives on edgefirst-decoder.
MaskResolution, drawing APIs Segmentation mask and bounding box annotation
align_width_for_gpu_pitch() and friends Pitch alignment helpers

Tiled inference (SAHI)

Small objects vanish when a high-resolution frame is squeezed into a 640×640 model input. The tiling APIs render an overlapping tile grid in a single GPU pass and merge per-tile detections back to full-frame coordinates, so small-object recall improves without a second inference pipeline.

Interoperability

convert(), draw_decoded_masks(), draw_proto_masks(), materialize_masks() and the other ImageProcessor entry points accept a tensor or ProtoData from any edgefirst.* package. Fused decode+draw lives on Decoder.draw_onto. Each extension module registers its own type objects (PyO3 issue #1444 — isinstance across packages is always False), so acceptance goes through duck-typed capsule protocols instead:

# 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.codec.Tensor):
    ...

edgefirst.image.EdgeFirstTensorExportable, EdgeFirstDecoderExportable and EdgeFirstProtoDataExportable are typing.Protocol classes (re-exported here from edgefirst.tensor / edgefirst.decoder) you can annotate a cross-package parameter with. See crates/python-common/INTEROP.md for the full protocol — capsule names, lifetime and ownership rules, and versioning.

Versioning and changelog

All five 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 8, 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:
Latest release

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 8, 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

image-processing computer-vision gpu edge-ai nv12

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_image-0.30.0-cp311-abi3-win_amd64.whl (5.3 MB view details)

Uploaded CPython 3.11+Windows x86-64

edgefirst_image-0.30.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.9 MB view details)

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

edgefirst_image-0.30.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.1 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

edgefirst_image-0.30.0-cp311-abi3-macosx_11_0_arm64.whl (2.0 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

edgefirst_image-0.30.0-cp38-abi3-win_amd64.whl (5.3 MB view details)

Uploaded CPython 3.8+Windows x86-64

edgefirst_image-0.30.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.9 MB view details)

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

edgefirst_image-0.30.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.1 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ ARM64

edgefirst_image-0.30.0-cp38-abi3-macosx_11_0_arm64.whl (2.0 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

File details

Details for the file edgefirst_image-0.30.0-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_image-0.30.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 2e109125cf0a4983c8e64cf94ae3d9a8273b073c656b083be6bdf89396d931d3
MD5 add38afc05b34e35de1a21fb39472e66
BLAKE2b-256 b7f5d90fe82ecdae2220560879df7a9a09c0e1d976db7b0df656bdf98161e6a0

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_image-0.30.0-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_image-0.30.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for edgefirst_image-0.30.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d925c007975e19e37192575757268a3701860eff651bddaba3887c494517cd05
MD5 8d1d41b585ff89e50e0935ae84e0dc6d
BLAKE2b-256 2950d98370d441c95301bad68d50260129eb1f8b4febe99bb1416ee149147724

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_image-0.30.0-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_image-0.30.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_image-0.30.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 239c66ede90049d187c271f93a35941c804481c07a44fc945d0c2f44509e4f4a
MD5 6a960e9a301b42d099aa57c76a45fed1
BLAKE2b-256 720cebb238bbd90141fb509f26d117055800f973621256a504d34605a909076a

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_image-0.30.0-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_image-0.30.0-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_image-0.30.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 cf114020460c3a343a93a3b38f333b242e5385fa1428b28144486462d54fbadb
MD5 19516df78ae39c9c441fa4bbcaa5292f
BLAKE2b-256 889fa80d925af212ddabb046dda94faed9dad266acda7115c4501a7223e2e423

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_image-0.30.0-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_image-0.30.0-cp38-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_image-0.30.0-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 770872d385115451a75b6f063c30a0f5cab8e8326d42db591107823fe7a0f6c5
MD5 94d9810e42924032556bef5d35163d8b
BLAKE2b-256 86a336a73536f6c1696f00d38c0ac25bff00ac9196e08986c894be40941c4abc

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_image-0.30.0-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_image-0.30.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for edgefirst_image-0.30.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 bd3984a69168cea17af8d105f8f7921451fa28e2c2908ca3236b11562971e895
MD5 60e6f463d2f44acb967f2fb48aa4b9b1
BLAKE2b-256 efbee73924467719f6743922027a563f987350dae04e89bd7363a6d296e6dbcc

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_image-0.30.0-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_image-0.30.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_image-0.30.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 f0d57bbe76bb89a1d7dbf1eb41d612c76ec766fe0390fe7a11530edc5a214515
MD5 8034bd593a743e0a8b949319df63f658
BLAKE2b-256 af6aa38e57eca8a15b6cea7898b702e7117319170dbeda9c7bb0bf3fe6eb2af1

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_image-0.30.0-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_image-0.30.0-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_image-0.30.0-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ef7d4c8e27ead3c5e3591b23a7968f01c257a000cf4b4f3913543e00cb6720b7
MD5 749cf43da97d1e07c93eeaa090ab4208
BLAKE2b-256 5230e8cc6af6880a6f28b247b4fee2dcb10576dfcc4fab1b3e38e2a734954cfc

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_image-0.30.0-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

This release

0.30.0 This release

8 files

0.29.4

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