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 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
NormalizationPreset, ColorMode Model input scaling and channel order
ConvertOptions.from_spec() Apply a model's preprocessing spec, interpolation included (e.g. edgefirst.decoder.ResolvedModelConfig.preprocessing)
ConvertOptions.content_region(), ContentRegion Where a convert puts the image content, for mapping results back (content_region=)
Interpolation, PadSpace Resampling filter (per convert with ConvertOptions(interpolation=...), else the processor's) and letterbox pad space
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 (a known PyO3 limitation — 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.

License

Apache-2.0

Metadata

Release files for edgefirst-image 0.41.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for edgefirst-image 0.41.0
File Actions
edgefirst_image-0.41.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for edgefirst_image-0.41.0-cp311-abi3-win_amd64.whl
edgefirst_image-0.41.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.11 abi3 Linux glibc 2.17+ x86-64 Details for edgefirst_image-0.41.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
edgefirst_image-0.41.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for edgefirst_image-0.41.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
edgefirst_image-0.41.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for edgefirst_image-0.41.0-cp311-abi3-macosx_11_0_arm64.whl
edgefirst_image-0.41.0-cp38-abi3-win_amd64.whl CPython 3.8 abi3 Windows x86-64 Details for edgefirst_image-0.41.0-cp38-abi3-win_amd64.whl
edgefirst_image-0.41.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.8 abi3 Linux glibc 2.17+ x86-64 Details for edgefirst_image-0.41.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
edgefirst_image-0.41.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.8 abi3 Linux glibc 2.17+ ARM64 Details for edgefirst_image-0.41.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
edgefirst_image-0.41.0-cp38-abi3-macosx_11_0_arm64.whl CPython 3.8 abi3 macOS 11.0+ ARM64 Details for edgefirst_image-0.41.0-cp38-abi3-macosx_11_0_arm64.whl

Total release size: 25.1 MB

Release files / edgefirst_image-0.41.0-cp311-abi3-win_amd64.whl

Download URL edgefirst_image-0.41.0-cp311-abi3-win_amd64.whl
Size 5.1 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
d92a57d4a2f541b749baf6e9042b45d1b84464dcbdbe7bc7fb8c49e4359135a4
BLAKE2b-256 checksum
How to use checksums
f3a616495c9375b15964d35d5b67103bbc806547a12abef986ae71700d15ec63
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_image-0.41.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL edgefirst_image-0.41.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 2.7 MB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
27bcb036832a075b8f79ed57489c0b32b61ce2378fb8ffdfbc13698e0e381dc2
BLAKE2b-256 checksum
How to use checksums
941348b6c12437474c48f48b432ca20d7a329c95aa5dac2f776c39e6a07d8bee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_image-0.41.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL edgefirst_image-0.41.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 2.3 MB
Tags CPython 3.11 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
5b5f3de15edbeafd1d178d34d372f9924db83ebd79051e6b926ddc07ec9c3c4f
BLAKE2b-256 checksum
How to use checksums
17e12c1fb46f10209bb20b534d7d56345d16d0ed7d1e62abba83f26261f25138
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_image-0.41.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL edgefirst_image-0.41.0-cp311-abi3-macosx_11_0_arm64.whl
Size 2.4 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
4e6b862ae04e50d5d9065d204462a65c8d9c2c92bd820282565ff19b6e1cc979
BLAKE2b-256 checksum
How to use checksums
951f28fe077f3b265d01c367d6b72613d56f8aac025ccca296e890b244847a3e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_image-0.41.0-cp38-abi3-win_amd64.whl

Download URL edgefirst_image-0.41.0-cp38-abi3-win_amd64.whl
Size 5.1 MB
Tags CPython 3.8 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
3c16bc86d1e52c38811979eb4e5c8c6665b5bb8a2741579899f31c6f8e3bb2c4
BLAKE2b-256 checksum
How to use checksums
e408851e7146851933fac1bf825454be171eb8374f901ef482057c48dd0dac8f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_image-0.41.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL edgefirst_image-0.41.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 2.7 MB
Tags CPython 3.8 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
eb1cf1264e94339d6586d1d7b89b7fa503d007ec9ccd950218ff3f8f0dd16869
BLAKE2b-256 checksum
How to use checksums
7877aff6c4f35c9f40b7aac4583d13226b5be0c6172b8564f470c4d71c306eec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_image-0.41.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL edgefirst_image-0.41.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 2.3 MB
Tags CPython 3.8 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
b044af8d8f883d05afa34e13cae1916abeaf9cc864adb0700cd35ff74c756678
BLAKE2b-256 checksum
How to use checksums
1026a372d158731c66725aed038651de539ede3d4dfb57e8edc6634f29d247e3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / edgefirst_image-0.41.0-cp38-abi3-macosx_11_0_arm64.whl

Download URL edgefirst_image-0.41.0-cp38-abi3-macosx_11_0_arm64.whl
Size 2.4 MB
Tags CPython 3.8 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
5d837122bc97525bcebf5ec7c0222a66108e6445075018247d83ee8f223e9356
BLAKE2b-256 checksum
How to use checksums
2174badcd9dd19095238bd4714f5e6efd8947f738c746dc537bd3f10a96fcafd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for edgefirst-image 0.41.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 8 files in this release have been uploaded with provenance metadata.

Select from 8 files

Attestation for edgefirst_image-0.41.0-cp311-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

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