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 (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.

License

Apache-2.0

Metadata

Release files for edgefirst-image 0.40.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.40.0
File Actions
edgefirst_image-0.40.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for edgefirst_image-0.40.0-cp311-abi3-win_amd64.whl
edgefirst_image-0.40.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.40.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
edgefirst_image-0.40.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for edgefirst_image-0.40.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
edgefirst_image-0.40.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for edgefirst_image-0.40.0-cp311-abi3-macosx_11_0_arm64.whl
edgefirst_image-0.40.0-cp38-abi3-win_amd64.whl CPython 3.8 abi3 Windows x86-64 Details for edgefirst_image-0.40.0-cp38-abi3-win_amd64.whl
edgefirst_image-0.40.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.40.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
edgefirst_image-0.40.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.8 abi3 Linux glibc 2.17+ ARM64 Details for edgefirst_image-0.40.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
edgefirst_image-0.40.0-cp38-abi3-macosx_11_0_arm64.whl CPython 3.8 abi3 macOS 11.0+ ARM64 Details for edgefirst_image-0.40.0-cp38-abi3-macosx_11_0_arm64.whl

Total release size: 25.1 MB

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

Download URL edgefirst_image-0.40.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
fed00311446ba6a58c67b41086ed0e397c62ae6b3d598515a974448bd10fe08f
BLAKE2b-256 checksum
How to use checksums
e685d9290ab08749b6b3480d797bed87d17018451d19cc73b3909670f36359da
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 5, 2026.

Transparency log

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

Download URL edgefirst_image-0.40.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
f0beec11b62af3ef472701a11eb29d262599e40c4ff8f10cf779bc9098b7bbce
BLAKE2b-256 checksum
How to use checksums
c0731275eaff51de7aed17abcdf8c1b1cbbbbc10f9cdbab83a04790e11b2ba5a
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 5, 2026.

Transparency log

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

Download URL edgefirst_image-0.40.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
db581ff6291680570605156f06fe7c332e1090300d40b349da048e26e5d4a49b
BLAKE2b-256 checksum
How to use checksums
2433200e44d2a3eb09ea7a0430c947cb822b3125ccd8efe7b71cfa260c5d3469
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 5, 2026.

Transparency log

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

Download URL edgefirst_image-0.40.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
2ba309788c0d29d5e2cc1ee72ce5203b07713f24a554561a7ee052b1f514bed5
BLAKE2b-256 checksum
How to use checksums
6923d3ea7a8ff87e22f60be65ac8a9013af0debd66596096e5004427693e213c
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 5, 2026.

Transparency log

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

Download URL edgefirst_image-0.40.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
7390175e42b5f4a1a7e41385f553c4b180c596df43f85126087632d8a76c2bf9
BLAKE2b-256 checksum
How to use checksums
356a4861baf8b33e4e27cedaef3e797d15b87eb0bb868964934d325ec4d98b7c
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 5, 2026.

Transparency log

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

Download URL edgefirst_image-0.40.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
e5ffde84319f5a633bfaab440d464e0834439c69ecab94927a4a7fd1d271453b
BLAKE2b-256 checksum
How to use checksums
4489044a48f234563b5d03e4adac5be5c3a6ab69bf757829416c5823578bc58d
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 5, 2026.

Transparency log

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

Download URL edgefirst_image-0.40.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
abbd84acc3fad17fbb1480fac0f4ea2726a1a6791f3f087f9a750cc062f087f8
BLAKE2b-256 checksum
How to use checksums
fe26bcad53489e6ae2d251c6acb681e18092c36a77d8614532487f134931e4d6
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 5, 2026.

Transparency log

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

Download URL edgefirst_image-0.40.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
d0ddfef18a8ebe26eb6e2cc31fb6d891a6844fa7fae7d74d7e4ece1e2be1af39
BLAKE2b-256 checksum
How to use checksums
b94d41a9098d974f5defc88fd0f16b5c0c44343709f9665593e09b989d832d59
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 5, 2026.

Transparency log

Security for edgefirst-image 0.40.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.40.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 5, 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