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

Uploaded CPython 3.11+Windows x86-64

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

Uploaded CPython 3.11+macOS 11.0+ ARM64

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

Uploaded CPython 3.8+Windows x86-64

edgefirst_image-0.29.4-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.4-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.4-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.4-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_image-0.29.4-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 eaba55764a5fa62a842e07cad1ceb19645d4059e8b7cb80172e8cf91302a0af7
MD5 d3e42ae1492a5a26d2502fda18c20909
BLAKE2b-256 5d3883cd7a5bb9893f98deeb5343751ef9c81c592a1075571572fa462e1b92e2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ad79cdc3d7fdb890fc520e3e0fe87aa9d15627589f28f85e7c87542689a90108
MD5 5088492dfef45cd0a23b0b16fbe1aec6
BLAKE2b-256 7bcd418599dd620736c5d56b3048977244e3f1b279d1beaeb722a82a7262b450

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0cbcf84a16a639f22b5459b115e852073306a1d358f37b6d3b0a6b38e869a24a
MD5 795965111ba1ded205aa4e9a8e6f5c5e
BLAKE2b-256 8b04c2570f0bc20da0f37833fc3640b6ae87a19b1d41254eb8b68de758f9c7e7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.4-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 dfe0d614bdfa71b2455166e4d3a3f2a81ff3710e0fad225d9f06fbbd83ccad07
MD5 45f8b0865acb148811e9bda795fbc9ad
BLAKE2b-256 1c227719ca64bc21c6875ea86cbfb15892eca6ba06bf0cdcd6b7039c80888abf

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.4-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 1017d9916f270dbe9743312f8e3438547fb37a5cd0145f685e877ee9949d53e1
MD5 dac8ddeadb285a4f8ea21824d029da37
BLAKE2b-256 0aa1dd9cf8786bcf8f199350639fc2d8aa10325092cb7a861383bb48ded2f982

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2802f5a5942a85ed1608a50b1fe36b921594c30285e267392261d8c0a400b474
MD5 fab8119ed3a67002549e24f7ee20a115
BLAKE2b-256 2de8ff5934a582e6271f93dfaa2ba6c0e2e27f4fbc184aeb9a53804d8cea0a57

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 672fef3444a2ca0e8b5d245b6fe9f808d787f42bfd4004fb0868201c194b5bd4
MD5 ee139617ee91cfcef61583a1b706b682
BLAKE2b-256 30a71cccfd401d5b1d90a666a6884fefff3158e0438c99fb582fb8dc5f519d1d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_image-0.29.4-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 00947ce4fc79ccd50e3ad08661088c40e86dc7ac024dc1c79b95cf75955eb08a
MD5 8e464875bd61b083f79b5957697de33a
BLAKE2b-256 853ed0cee9d6073f1dd05807ed97a3e4b6f436cc2ba72f06e80edf50a3952c09

See more details on using hashes here.

Provenance

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

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