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.29.4-cp311-abi3-win_amd64.whl (970.9 kB view details)

Uploaded CPython 3.11+Windows x86-64

edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.2 MB view details)

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

edgefirst_tensor-0.29.4-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.29.4-cp311-abi3-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

edgefirst_tensor-0.29.4-cp38-abi3-win_amd64.whl (974.8 kB view details)

Uploaded CPython 3.8+Windows x86-64

edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.2 MB view details)

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

edgefirst_tensor-0.29.4-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.29.4-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.29.4-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.4-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 09fafcd14e9e30636df48762dd5d35b1e551a29030c0d5f56834bf4468f78c39
MD5 e33b62b375a0204b016277861c3d32ec
BLAKE2b-256 c2ab365b25f7062cd5d84882fd88bd6b449c80da45fad09dfe48f5e68e208961

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d9a5960a107f76de589f896e214297707ab2e9f48fc63f953530b6cacd062f53
MD5 5c88f981aa8cf729351934bada722aa8
BLAKE2b-256 38ce8918c868689d4a245fbbb97b5a5552700c63bdb7bf7d6ef7e3037bea6874

See more details on using hashes here.

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

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.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 c2f50af41e61faffd1cca62f2af4b962496c041967e4899c9a323b0a4d8363a6
MD5 c78f107f112e3bafd2a6cfd06e52a5ed
BLAKE2b-256 655ac86a75be6f6f523395bbab889278dbb3e7e6f3bbadc43d27d5a65e159b73

See more details on using hashes here.

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

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.29.4-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.4-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a1725038eed7f66e5c4c9f18b77fecbe5f8ab2a7e75efe8d7f3f84ead24ed4ed
MD5 24c8ce760616cb43656aa04ce90a8f97
BLAKE2b-256 b48b8439a5c0eea6fca2f35d954b136f445331ee7d274b8c53d9959df55a67d7

See more details on using hashes here.

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

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.29.4-cp38-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.4-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 5b5d82c63f1870ab88264a1fd36eb645db7f183eec2efee8f62be03ba5a98295
MD5 99c9051a027d02e3603bc56d178dbf35
BLAKE2b-256 2235329a4c05fe0fac6df0ab396601373842a7cf79758168556ddfc965c78d0a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 87b45763aabd4f3e65e1ff80b856162f2206da5f08085bd57ef766af8b99a576
MD5 96d9f0bb677b7423403d043e734c7cb4
BLAKE2b-256 0dd795daf72592499adfecb25d4dfc91bf83c16b7bc836b3ba2677b5afec3be0

See more details on using hashes here.

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

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.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ea4a9a957fa131caf99a1b1540ab787d151964dc23cddbffd9af85dda2f5ca51
MD5 c912be6540c090373ae5fa89739634a7
BLAKE2b-256 6d3f532051115f729964033fd07b25b4d5adfc613a92a170c3543e20600ace14

See more details on using hashes here.

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

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.29.4-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.4-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 811b17c90f0f01fe763d61f8239536c5d4f7173a11aff099baae5f4be620466f
MD5 d2baf78ecef36942cfab8ad9db7d3175
BLAKE2b-256 63156d33055efe7ab8568019629ce349c250d17e7b9affd403774cfcd1524e29

See more details on using hashes here.

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

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