Skip to main content

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 with PBO transfers — 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_ANGLE_ADAPTER 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 #1444isinstance 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

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.29.3-cp311-abi3-win_amd64.whl (5.2 MB view details)

Uploaded CPython 3.11+Windows x86-64

edgefirst_image-0.29.3-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.29.3-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.29.3-cp311-abi3-macosx_11_0_arm64.whl (1.9 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

edgefirst_image-0.29.3-cp38-abi3-win_amd64.whl (5.2 MB view details)

Uploaded CPython 3.8+Windows x86-64

edgefirst_image-0.29.3-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.29.3-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.29.3-cp38-abi3-macosx_11_0_arm64.whl (1.9 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

File details

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.3-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 2f880e16a8eb94cf8d1ea7c5aa01efa8a406f87523bd2fccdfc4ead15bd75ee9
MD5 77071f75fa31c32159409a0e5ec3dd65
BLAKE2b-256 70bea356f3f1a69c8c1d95b45863a27ef88ff6269dad6884f8ab43eeed5b2032

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.3-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b2380eb796b946a74fb841a4dc293310d1d0f694aa594e2c9e9a210f989a0c26
MD5 1385cdb8db3551c047640ad637ebecec
BLAKE2b-256 f4a47e0f64aa37bedda428022f8b32481e2bc3c4452c12d356c9118f899d49a1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.3-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 62a1eccbd0449ce677c9b4259f57122abc7a9f780a40037d1bc4160a9ceec9b4
MD5 1e95ac2b89e27391be5ff1e03399b11f
BLAKE2b-256 b78fde38aa779371584fb9cb9568e2371adfef7c5c7f37691de94d729ad530f6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.3-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7f86e5e17e88cd1dcaf14a0dfa9885de7b9f98d14360df8e07b90d3618ce70fc
MD5 35cbaf69a2fe833528d22f112d003d43
BLAKE2b-256 3f62922d1e4cbd26d0aba5204656f2968cd6176a4ef36204d623ae6f6d17e437

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.3-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 1ed7c463f8d489eb8d55fe8409c5f4c15dd05e9267a2737f12e80bedf00d5592
MD5 f4dc7486155dae9ac14bf8c46dff69f6
BLAKE2b-256 c0e1a8a080d7c983f101ad3fa578cf83a470712382559defff8a02ff3912609a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 43791bd0f7aa06088bb85d0e44c27bb6cb38acd5153d5cb24c5cc13035a72db2
MD5 d5c5179bee92d3a89c1a44762d0bb2b9
BLAKE2b-256 e496567ba1b0d546c054d1bc44bfa0a77deed2820e85cf489be7e06d2d34c8aa

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 2257b41a91f70bd1759c02969be76778496e6bba0d79678ca8addc704362aae2
MD5 45ba2cd339c197dfb514b7e595cc1403
BLAKE2b-256 9172cf47705a179ae8389ced010fa2341c65783be35c189e49e385091ee849bc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.3-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 df79d3a3f86a9f5711374aec7e1279a81e606866f20d8397b833d77b58e11260
MD5 83a8dd2ad498b3d36192a511eacd6984
BLAKE2b-256 1301c0c3adadcd4910bd63b1e5776c2e1990de38a756fdc8b663362ef8c65061

See more details on using hashes here.

Provenance

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

0.29.4

8 files

This release

0.29.3 This release

8 files

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