Skip to main content

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.

PyPI License

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

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_tensor-0.30.0-cp311-abi3-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.11+Windows x86-64

edgefirst_tensor-0.30.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ x86-64

edgefirst_tensor-0.30.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.2 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

edgefirst_tensor-0.30.0-cp311-abi3-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

edgefirst_tensor-0.30.0-cp38-abi3-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.8+Windows x86-64

edgefirst_tensor-0.30.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ x86-64

edgefirst_tensor-0.30.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.2 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ ARM64

edgefirst_tensor-0.30.0-cp38-abi3-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

File details

Details for the file edgefirst_tensor-0.30.0-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.30.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 81e99849811956c7d55ce272599e6c70fc03ab69d9a32c89a05bf25935898868
MD5 ee6675747376644060058bddd9aa6d36
BLAKE2b-256 579131d30472a3c9f90671f48704aebeb9c36838fa993553ab8b182a15af8678

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_tensor-0.30.0-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_tensor-0.30.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.30.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 0e0a9bcca11e3bc212c204afe64e4c5c879fbd93e4d9d1221353046f7d961c98
MD5 57ab90a0647f16abea089a776a131574
BLAKE2b-256 2f1a9806153b29b53a37de6549a0fdde1098ddbb067170c2d5d11d038d4eb870

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_tensor-0.30.0-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_tensor-0.30.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.30.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 592c7719f0575e9852d0943be45d6f7ff56bdbd39040201c3a9b40f9ff6ffea3
MD5 b2f94cdeea2f2d8671fbf8ec8a9ea35c
BLAKE2b-256 0f2610782a9b1887bf1436c8bd80b897d5fec4543de3a17d127e5921c37ba085

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_tensor-0.30.0-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_tensor-0.30.0-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.30.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4a68a43bb272c786798751123bcdd29c157539e7c227624e3dd69aa3d9abb377
MD5 53f8bd624ddcc6510caaf26e24c54db2
BLAKE2b-256 46ac0c29bf54baa361809228e42130eef151563170ba7fc272f076e3364da0d2

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_tensor-0.30.0-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_tensor-0.30.0-cp38-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.30.0-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 b0b5b39490283b9aedb99238b833407d7a65201d9bfb982eb49358155132a87e
MD5 e2a83f1564443d0cae00e366c245f1c3
BLAKE2b-256 0f8e26a2e9c03a6f96a0195b53376e8badc09b3defe58b90287781ada963baaa

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_tensor-0.30.0-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_tensor-0.30.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.30.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2c5355453e53091a7a6ac6def41ea48abe4691cf2e73477c93a58194646ceb7b
MD5 6331034f75e0e1bdcd046e45e0bb13f9
BLAKE2b-256 3fae86ed33fbdf99f5877f4a6b29d12c6060919fe5c8aaaf5df17e96067d4ddb

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_tensor-0.30.0-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_tensor-0.30.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.30.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e79f2699a477f56b9244385dbc9e4c34cce4d766e0bb1696d498abe3dc86e591
MD5 58f51e4d987922208ee2ce170bbab9a8
BLAKE2b-256 3b8275cc2ad41403d2cdefae3382a675db0eb8f8df9bf18a49810bbbb70a205d

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_tensor-0.30.0-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_tensor-0.30.0-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.30.0-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6e51e2425b753129d0e524ae5bf895b71f3898f931a2d7a679dfd299497d04bf
MD5 37696c8c0000d1bbd6d4f015dc908106
BLAKE2b-256 f6364033ca35072336c25654100c522c3506a3a7a471f9eed35979475de1a762

See more details on using hashes here.

Provenance

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

This release

0.30.0 This release

8 files

0.29.4

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