edgefirst-tensor
Zero-copy tensor memory for edge AI inference pipelines — DMA-BUF, IOSurface, AHardwareBuffer, OpenGL PBO, POSIX shared memory and heap behind one Python API.
Part of the EdgeFirst HAL
edgefirst-tensor 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 (this package) |
edgefirst-codec |
JPEG and PNG decoding directly into pre-allocated tensors |
edgefirst-image |
GPU-accelerated colour conversion, resize, letterbox, tiling and drawing |
edgefirst-decoder |
YOLO and ModelPack output decoding |
edgefirst-tracker |
ByteTrack multi-object tracking |
This package is the foundation the other four build on; installing any of them installs this one.
Installation
pip install edgefirst-tensor
Requires Python 3.8 or newer and NumPy. Wheels are published for Linux (x86_64, aarch64), macOS (arm64), and Windows (x86_64).
The _codec, _image, _decoder and _tracker extensions locate libedgefirst_tensor.so via DT_RUNPATH=$ORIGIN/../tensor. That assumes every edgefirst.* package lands in the same site-packages tree, which pip normally guarantees. A split layout (pip install --target, some vendored trees) will fail at import with libedgefirst_tensor.so.0: cannot open shared object file. On Windows the library is edgefirst_tensor.dll in that same edgefirst/tensor/ directory and there is no rpath: each sibling package's __init__.py registers the directory with os.add_dll_directory() before loading its extension, because Python 3.8+ does not consult PATH for extension-module DLLs.
Packages install under the PEP 420 edgefirst.* namespace, so imports are edgefirst.tensor, edgefirst.codec, and so on. No package ships an edgefirst/__init__.py — a single one would shadow the namespace and hide its siblings.
Quick start
Allocate an image tensor, fill it through a mapped host view, and read it back as NumPy:
import numpy as np
from edgefirst.tensor import Tensor, PixelFormat
# Allocate once; a real pipeline reuses the tensor every frame.
# mem=None selects the best backend available on the platform.
tensor = Tensor.image(1920, 1080, PixelFormat.Rgb, None, "readwrite")
with tensor.map() as view:
frame = np.asarray(view) # shape, dtype and strides all carried
frame[:] = 128
print(tensor.shape, tensor.format, tensor.dtype)
map() returns a HostView implementing the buffer protocol, so np.asarray wraps the tensor's memory without copying — and because the view publishes shape, dtype and the real row stride, no manual reshape is needed and a pitch-aligned DMA buffer is read correctly rather than sheared. The view is released when the with block exits.
The map also owns its cache-coherency bracket, and access chooses the direction. The default "readwrite" flushes the whole buffer on release; a reader does not need that, and on a non-coherent Arm DMA-BUF backing skipping it is a per-frame saving:
with tensor.map("read") as view:
frame = np.asarray(view) # read-only view, not writable
pin_host() is the exception: it is deliberately decoupled from coherency so a pinned address can survive across convert() calls, which is why it pairs with an explicit cpu_access() bracket instead.
Handing memory to an external runtime
pin_host() returns a stable host address that outlives any map guard and carries no borrow of the tensor, so a pinned buffer can be given to an inference runtime (TFLite custom allocations, ONNX Runtime external tensors) while your frame loop keeps writing to it:
pin = tensor.pin_host("readwrite")
print(hex(pin.ptr), pin.len, pin.alignment)
# pin.ptr stays valid for the lifetime of `pin` — across re-maps and across
# ImageProcessor.convert() calls — so an external runtime can hold on to it.
pin.release()
What this package provides
| API | Purpose |
|---|---|
Tensor |
Allocation, reshape, host mapping, NumPy interchange |
Tensor.image() |
Allocate with image dimensions and a pixel format |
Tensor.map() / HostView |
Buffer-protocol host access, released on scope exit |
Tensor.pin_host() / HostPin |
Stable host address for external runtimes |
Tensor.cuda_map() / CudaMap |
Zero-copy CUDA device pointer for TensorRT (Jetson) |
TensorMemory, PixelFormat, Region |
Backend selection, pixel layout, sub-regions |
Quantization, Colorimetry |
Quantization parameters and colour metadata |
is_dma_available() and friends |
Runtime capability probes |
Tracing, build_info() |
Diagnostics |
Interoperability
Each edgefirst-* package is a separate PyO3 extension module, so edgefirst.tensor.Tensor and, say, edgefirst.codec.Tensor are different Python classes even though they wrap the same Rust type — a known PyO3 limitation (issue #1444). A tensor still crosses package boundaries safely, through the __edgefirst_tensor__ capsule protocol every Tensor implements:
# 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.image.Tensor):
...
edgefirst.tensor.EdgeFirstTensorExportable is a typing.Protocol you can annotate a cross-package parameter with, so a type checker accepts a tensor from any edgefirst.* package. See crates/python-common/INTEROP.md for the full protocol — capsule names, lifetime and ownership rules, and versioning.
Versioning and changelog
All four 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
- Changelog — release notes for all packages
- Source — the
halmonorepo - Issue tracker
- Package documentation — the underlying Rust crate, including the memory backend matrix and CUDA mapping
- EdgeFirst
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
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file edgefirst_tensor-0.29.4-cp311-abi3-win_amd64.whl.
File metadata
- Download URL: edgefirst_tensor-0.29.4-cp311-abi3-win_amd64.whl
- Upload date:
- Size: 970.9 kB
- Tags: CPython 3.11+, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
09fafcd14e9e30636df48762dd5d35b1e551a29030c0d5f56834bf4468f78c39
|
|
| MD5 |
e33b62b375a0204b016277861c3d32ec
|
|
| BLAKE2b-256 |
c2ab365b25f7062cd5d84882fd88bd6b449c80da45fad09dfe48f5e68e208961
|
Provenance
The following attestation bundles were made for edgefirst_tensor-0.29.4-cp311-abi3-win_amd64.whl:
Publisher:
release.yml on EdgeFirstAI/hal
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
edgefirst_tensor-0.29.4-cp311-abi3-win_amd64.whl -
Subject digest:
09fafcd14e9e30636df48762dd5d35b1e551a29030c0d5f56834bf4468f78c39 - Sigstore transparency entry: 2718491064
- Sigstore integration time:
-
Permalink:
EdgeFirstAI/hal@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Branch / Tag:
refs/tags/v0.29.4 - Owner: https://github.com/EdgeFirstAI
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 1.2 MB
- Tags: CPython 3.11+, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d9a5960a107f76de589f896e214297707ab2e9f48fc63f953530b6cacd062f53
|
|
| MD5 |
5c88f981aa8cf729351934bada722aa8
|
|
| BLAKE2b-256 |
38ce8918c868689d4a245fbbb97b5a5552700c63bdb7bf7d6ef7e3037bea6874
|
Provenance
The following attestation bundles were made for edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:
Publisher:
release.yml on EdgeFirstAI/hal
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl -
Subject digest:
d9a5960a107f76de589f896e214297707ab2e9f48fc63f953530b6cacd062f53 - Sigstore transparency entry: 2718489978
- Sigstore integration time:
-
Permalink:
EdgeFirstAI/hal@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Branch / Tag:
refs/tags/v0.29.4 - Owner: https://github.com/EdgeFirstAI
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 1.2 MB
- Tags: CPython 3.11+, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c2f50af41e61faffd1cca62f2af4b962496c041967e4899c9a323b0a4d8363a6
|
|
| MD5 |
c78f107f112e3bafd2a6cfd06e52a5ed
|
|
| BLAKE2b-256 |
655ac86a75be6f6f523395bbab889278dbb3e7e6f3bbadc43d27d5a65e159b73
|
Provenance
The following attestation bundles were made for edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:
Publisher:
release.yml on EdgeFirstAI/hal
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl -
Subject digest:
c2f50af41e61faffd1cca62f2af4b962496c041967e4899c9a323b0a4d8363a6 - Sigstore transparency entry: 2718492363
- Sigstore integration time:
-
Permalink:
EdgeFirstAI/hal@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Branch / Tag:
refs/tags/v0.29.4 - Owner: https://github.com/EdgeFirstAI
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file edgefirst_tensor-0.29.4-cp311-abi3-macosx_11_0_arm64.whl.
File metadata
- Download URL: edgefirst_tensor-0.29.4-cp311-abi3-macosx_11_0_arm64.whl
- Upload date:
- Size: 1.1 MB
- Tags: CPython 3.11+, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a1725038eed7f66e5c4c9f18b77fecbe5f8ab2a7e75efe8d7f3f84ead24ed4ed
|
|
| MD5 |
24c8ce760616cb43656aa04ce90a8f97
|
|
| BLAKE2b-256 |
b48b8439a5c0eea6fca2f35d954b136f445331ee7d274b8c53d9959df55a67d7
|
Provenance
The following attestation bundles were made for edgefirst_tensor-0.29.4-cp311-abi3-macosx_11_0_arm64.whl:
Publisher:
release.yml on EdgeFirstAI/hal
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
edgefirst_tensor-0.29.4-cp311-abi3-macosx_11_0_arm64.whl -
Subject digest:
a1725038eed7f66e5c4c9f18b77fecbe5f8ab2a7e75efe8d7f3f84ead24ed4ed - Sigstore transparency entry: 2718489464
- Sigstore integration time:
-
Permalink:
EdgeFirstAI/hal@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Branch / Tag:
refs/tags/v0.29.4 - Owner: https://github.com/EdgeFirstAI
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file edgefirst_tensor-0.29.4-cp38-abi3-win_amd64.whl.
File metadata
- Download URL: edgefirst_tensor-0.29.4-cp38-abi3-win_amd64.whl
- Upload date:
- Size: 974.8 kB
- Tags: CPython 3.8+, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5b5d82c63f1870ab88264a1fd36eb645db7f183eec2efee8f62be03ba5a98295
|
|
| MD5 |
99c9051a027d02e3603bc56d178dbf35
|
|
| BLAKE2b-256 |
2235329a4c05fe0fac6df0ab396601373842a7cf79758168556ddfc965c78d0a
|
Provenance
The following attestation bundles were made for edgefirst_tensor-0.29.4-cp38-abi3-win_amd64.whl:
Publisher:
release.yml on EdgeFirstAI/hal
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
edgefirst_tensor-0.29.4-cp38-abi3-win_amd64.whl -
Subject digest:
5b5d82c63f1870ab88264a1fd36eb645db7f183eec2efee8f62be03ba5a98295 - Sigstore transparency entry: 2718490099
- Sigstore integration time:
-
Permalink:
EdgeFirstAI/hal@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Branch / Tag:
refs/tags/v0.29.4 - Owner: https://github.com/EdgeFirstAI
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 1.2 MB
- Tags: CPython 3.8+, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
87b45763aabd4f3e65e1ff80b856162f2206da5f08085bd57ef766af8b99a576
|
|
| MD5 |
96d9f0bb677b7423403d043e734c7cb4
|
|
| BLAKE2b-256 |
0dd795daf72592499adfecb25d4dfc91bf83c16b7bc836b3ba2677b5afec3be0
|
Provenance
The following attestation bundles were made for edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:
Publisher:
release.yml on EdgeFirstAI/hal
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl -
Subject digest:
87b45763aabd4f3e65e1ff80b856162f2206da5f08085bd57ef766af8b99a576 - Sigstore transparency entry: 2718493621
- Sigstore integration time:
-
Permalink:
EdgeFirstAI/hal@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Branch / Tag:
refs/tags/v0.29.4 - Owner: https://github.com/EdgeFirstAI
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 1.2 MB
- Tags: CPython 3.8+, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ea4a9a957fa131caf99a1b1540ab787d151964dc23cddbffd9af85dda2f5ca51
|
|
| MD5 |
c912be6540c090373ae5fa89739634a7
|
|
| BLAKE2b-256 |
6d3f532051115f729964033fd07b25b4d5adfc613a92a170c3543e20600ace14
|
Provenance
The following attestation bundles were made for edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:
Publisher:
release.yml on EdgeFirstAI/hal
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl -
Subject digest:
ea4a9a957fa131caf99a1b1540ab787d151964dc23cddbffd9af85dda2f5ca51 - Sigstore transparency entry: 2718492439
- Sigstore integration time:
-
Permalink:
EdgeFirstAI/hal@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Branch / Tag:
refs/tags/v0.29.4 - Owner: https://github.com/EdgeFirstAI
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file edgefirst_tensor-0.29.4-cp38-abi3-macosx_11_0_arm64.whl.
File metadata
- Download URL: edgefirst_tensor-0.29.4-cp38-abi3-macosx_11_0_arm64.whl
- Upload date:
- Size: 1.1 MB
- Tags: CPython 3.8+, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
811b17c90f0f01fe763d61f8239536c5d4f7173a11aff099baae5f4be620466f
|
|
| MD5 |
d2baf78ecef36942cfab8ad9db7d3175
|
|
| BLAKE2b-256 |
63156d33055efe7ab8568019629ce349c250d17e7b9affd403774cfcd1524e29
|
Provenance
The following attestation bundles were made for edgefirst_tensor-0.29.4-cp38-abi3-macosx_11_0_arm64.whl:
Publisher:
release.yml on EdgeFirstAI/hal
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
edgefirst_tensor-0.29.4-cp38-abi3-macosx_11_0_arm64.whl -
Subject digest:
811b17c90f0f01fe763d61f8239536c5d4f7173a11aff099baae5f4be620466f - Sigstore transparency entry: 2718491787
- Sigstore integration time:
-
Permalink:
EdgeFirstAI/hal@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Branch / Tag:
refs/tags/v0.29.4 - Owner: https://github.com/EdgeFirstAI
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b8a376e6e76a26bab9ab63c1ae87c48b579e53d2 -
Trigger Event:
push
-
Statement type: