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

Uploaded CPython 3.11+Windows x86-64

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

Uploaded CPython 3.11+macOS 11.0+ ARM64

edgefirst_tensor-0.29.3-cp38-abi3-win_amd64.whl (974.1 kB view details)

Uploaded CPython 3.8+Windows x86-64

edgefirst_tensor-0.29.3-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.3-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.3-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.3-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.3-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 274bbc67fb6dd38688d9041e0c707e23b02d8d47b28cdf5aa5804915d81c59b6
MD5 6f17e05f69103b0ac1282c501a94f666
BLAKE2b-256 2a97ac297ff978ee31a0c8e34e35cc35806075fe53c76e6cd6be8f158446b56a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.3-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 726e4243f6631c0b51034b207d5a8defb652d4f5abb61099f0de8109ee2902b4
MD5 eb53ebca52043b3c5f0b85fa2f7c09a9
BLAKE2b-256 ae1aace3b8469ea1413966cf09980f93fda75bf6d35e6dbbd48b82e0107ed00b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.3-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 bb5205babd349a23970058e08f4cda4779768ff3e8f6b66f59b740421ce4f457
MD5 5938ed8f5dd53152d004543835160d3f
BLAKE2b-256 f9376f8b394c28c6b39fd19a942a7256dfb1eb346a2087fb2bc98155629b9a8e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.3-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 23df07900f08bb374ff9fe4eb43d335facb20ee457e3b078922fe48a13f0eddc
MD5 d825234c5b6e9567fae0fc829da0f4dd
BLAKE2b-256 a082bf741a86bf6fdc10b7d373e865935d43ac3ba0b305ed4456967f38065a9b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.3-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 a72464cd8146b7fb92f5b20147e2555b41e77d913390bf80b0a775d3157d54b6
MD5 d069977cd22ca49f590b0aea5cd1ae4b
BLAKE2b-256 5c9fce6c3d281f7b68cb0f9ede01b6b5b1aaa677577338c613c1df9c2e68fe88

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ab7dc8c07abd354c17baf02f9c44b82e7b3ec1504fe61c831eed4855168b9eec
MD5 ebf0a1589b00704cf67592a5834bbafd
BLAKE2b-256 9a2bea71263c33923a122a12d1fb9285fe8aaae962614f8bd1471985c8d950fc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 c6f7538bfd17beafdfad57493cbf6c2a71b388453de14487dc1db403f3331252
MD5 c6a9aaac2d51b06722b3c3e9e115947c
BLAKE2b-256 a46b046c8a8fc87f52a3ee4495fec07304a9633fd40b7ef78d1600bb87ad43f9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_tensor-0.29.3-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3231cbaedbbeb1f1bae7465b1a40d19ceb7a135fde822ddcbae46d6775073bc1
MD5 95e0ab440a9deef4dcf7a71e4d8dddad
BLAKE2b-256 a9ad869248d32a79be769edb60e1268eccec3f63c2801b9b06dc45821c6c31e7

See more details on using hashes here.

Provenance

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

0.29.4

8 files

This release

0.29.3 This release

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