edgefirst-decoder

YOLO and ModelPack output decoding for edge AI — bounding boxes, segmentation masks and multi-object tracking, without leaving native code.

PyPI License

Part of the EdgeFirst HAL

edgefirst-decoder 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
edgefirst-decoder YOLO and ModelPack output decoding (this package)
edgefirst-tracker ByteTrack multi-object tracking

Installation

pip install edgefirst-decoder

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

Packages install under the PEP 420 edgefirst.* namespace, so the import is edgefirst.decoder.

Quick start

Describe your model's outputs, then decode inference results into detections:

import numpy as np
from edgefirst.decoder import Decoder, Output, Tensor

decoder = Decoder.new_from_outputs(
    outputs=[Output.detection(shape=[1, 84, 8400])],
    score_threshold=0.25,
    iou_threshold=0.45,
)

# `raw` is what your inference runtime produced. Copy it into a HAL tensor;
# in a real pipeline the runtime writes into the tensor directly instead.
raw = np.zeros((1, 84, 8400), dtype=np.float32)
raw[0, 0:4, 0] = [0.5, 0.5, 0.2, 0.2]  # cx, cy, w, h (normalized)
raw[0, 4, 0] = 0.9  # class 0 score

output = Tensor(raw.shape, "float32")
output.from_numpy(raw)

boxes, scores, classes, masks = decoder.decode([output])
print(np.asarray(boxes), np.asarray(scores), np.asarray(classes))

Boxes come back normalized. NMS runs by default in class-agnostic mode; pass nms=Nms.ClassAware or nms=None to change or bypass it.

For a quantized model, attach the quantization parameters to the output description so the decoder dequantizes as it reads:

Output.detection(shape=[1, 84, 8400]).with_quantization(scale=0.004, zero_point=-123)

Configurations can also be supplied as a dictionary, or as JSON or YAML, with Decoder(config_dict), Decoder.new_from_json_str() and Decoder.new_from_yaml_str(). Set decoder_version=DecoderVersion.Yolo26 for end-to-end Ultralytics models.

decode() and friends accept a model-output tensor from any edgefirst.* package, not just this one — they cross packages through the capsule protocol, not by type. Value types such as PixelFormat and TensorMemory are accepted from any package too, comparing and hashing equal across packages by value. Importing Tensor from edgefirst.decoder 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.

Segmentation masks

decode() returns masks at prototype resolution as arrays of shape (H, W, C):

  • Instance segmentation (YOLO): C == 1, a binary per-instance mask — threshold at 128.
  • Semantic segmentation (ModelPack): C == num_classes, per-pixel class scores — take argmax over the last axis.

Multi-object tracking

Tracking lives in the standalone edgefirst-tracker wheel. Decoder.decode_tracked accepts any object with an update method, including edgefirst.tracker.ByteTrack:

from edgefirst.tracker import ByteTrack

tracker = ByteTrack()
boxes, scores, classes, masks, tracks = decoder.decode_tracked(
    tracker, timestamp_ns, outputs
)

Schema inference for Ultralytics exports

A vanilla Ultralytics YOLOv8/11/26 export carries no edgefirst.json, but its own metadata and tensor shapes are enough to derive one. infer_ultralytics_schema reads what your runtime reports and returns a schema you can hand straight to Decoder():

import onnxruntime as ort
from edgefirst.decoder import Decoder, infer_ultralytics_schema

sess = ort.InferenceSession("yolov8n.onnx", providers=["CPUExecutionProvider"])

# Ultralytics ONNX exports are float32 throughout and unquantized. A TFLite
# interpreter reports dtype and quantization per tensor instead; pass those as
# a 4th element on each output: (name, shape, dtype, (scales, zero_points)).
inputs = [(t.name, list(t.shape), "float32") for t in sess.get_inputs()]
outputs = [(t.name, list(t.shape), "float32") for t in sess.get_outputs()]
metadata = dict(sess.get_modelmeta().custom_metadata_map)

inferred = infer_ultralytics_schema("onnx", inputs, outputs, metadata)
print(inferred.description)  # "Ultralytics YOLOv8/11 detect, 80 classes"

decoder = Decoder(inferred.schema, score_threshold=0.25, iou_threshold=0.45)

boxes, scores, classes, masks = decoder.decode(model_outputs)
print(inferred.labels[classes[0]])  # class name for the first detection

The result is a named tuple, so schema, labels, description = inferred works too — but two of the three fields are strings, and naming them is cheaper than remembering the order.

source decides the box convention: Ultralytics ONNX exports report pixel-space coordinates, TFLite exports report [0, 1]. "other" is accepted but refused by inference rather than defaulted — that convention follows the exporter, is not derivable from shapes, and guessing it scales every box by the input size. Supported dtype strings are "int8", "uint8", "int16", "uint16", "int32", "uint32", "float16" and "float32".

schema is a plain dict, ready for Decoder(schema) — there is no JSON string to parse back. labels is the class names in index order, which is what maps decode()'s class indices back to names.

Shapes must be concrete. A model exported with dynamic=True reports a symbolic axis ('batch' from ONNX, -1 from TFLite); those are refused with a ValueError naming the tensor and axis, because the layout rules need real sizes.

The schema pins the NMS mode and leaves the thresholds to you. Ultralytics runs NMS class-aware (agnostic=False), so an inferred pre-NMS schema says so rather than inheriting Decoder's class-agnostic default, which would suppress a box against an overlapping box of a different class. Passing nms= still overrides. Thresholds are not inferable, and Decoder's defaults (score_threshold=0.1, iou_threshold=0.7) are not Ultralytics' (0.25/0.45) — pass them as shown above. YOLO26 end-to-end exports apply NMS in-graph and carry no mode at all.

ValueError is raised for anything that is not a recognizable Ultralytics export — missing or unparsable metadata, an unsupported task (only detect and segment; pose, OBB and classify are refused), or a class count that does not fit the output width. Metadata and shapes are cross-checked against each other, so a disagreement is reported rather than resolved by preference.

What this package provides

API Purpose
Decoder Model output decoding to boxes, scores, classes and masks
Decoder.new_from_outputs() Programmatic configuration from Output descriptions
Decoder.new_from_json_str() / new_from_yaml_str() Configuration from JSON or YAML
infer_ultralytics_schema() Schema derived from a vanilla Ultralytics export's own metadata and shapes
InferredSchema Named tuple returned by infer_ultralytics_schema()
Output, DimName Output shape and semantics description
Nms, DecoderType, DecoderVersion NMS mode and model family selection
ProtoData Mask prototypes and coefficients
Decoder.draw_onto Fused decode + draw onto an ImageProcessor
MatchMetric, MergeConfig, TiledFrameAccumulator SAHI tile-merge

Interoperability

decode() / decode_proto() / decode_tracked() accept model-output tensors from any edgefirst.* package, and Decoder / ProtoData instances produced here hand off to edgefirst.image's ImageProcessor the same way. Each extension module registers its own type objects (PyO3 issue #1444 — isinstance across packages is always False, even for two objects wrapping the same Rust type), 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.image.Tensor):
    ...

edgefirst.decoder.EdgeFirstTensorExportable (re-exported from edgefirst.tensor), EdgeFirstDecoderExportable and EdgeFirstProtoDataExportable are typing.Protocol classes you can annotate a cross-package parameter with. See crates/python-common/INTEROP.md for the full protocol.

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

Project links

Data verified by PyPI on Sep 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.30.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for au-zone from gravatar.com au-zone

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Au-Zone Technologies

GitHub Statistics

Data verified by PyPI on Sep 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.8

Tags

yolo object-detection segmentation nms edge-ai

Classifiers

Report project as malware

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_decoder-0.29.4-cp311-abi3-win_amd64.whl (2.1 MB view details)

Uploaded CPython 3.11+Windows x86-64

edgefirst_decoder-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.2 MB view details)

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

edgefirst_decoder-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.0 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

edgefirst_decoder-0.29.4-cp311-abi3-macosx_11_0_arm64.whl (2.0 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

edgefirst_decoder-0.29.4-cp38-abi3-win_amd64.whl (2.1 MB view details)

Uploaded CPython 3.8+Windows x86-64

edgefirst_decoder-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.2 MB view details)

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

edgefirst_decoder-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.0 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ ARM64

edgefirst_decoder-0.29.4-cp38-abi3-macosx_11_0_arm64.whl (2.0 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

File details

Details for the file edgefirst_decoder-0.29.4-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_decoder-0.29.4-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 55e6bd1cc31f0b9f95d53741fab0c6f392b8afb4cb7676e5e156e52541984cae
MD5 9da614a9183cc01ffd2b934d135e89dd
BLAKE2b-256 38de5267e2dcd97b1794c9751540b347953d7ae6468d93b5f9f3bc120a3556de

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_decoder-0.29.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 dd7a7d9d4b7d7debe3de628743cb322ef9531c9c30ee0b47c3911fbb25661e08
MD5 d49d9b1132021d2a62bafbea7cae0ab8
BLAKE2b-256 96ade4354c3dd151c796d0fda0654332802f8b9fd12acd726e7a62865f68e0e9

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_decoder-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_decoder-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_decoder-0.29.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ad4c7b1d60844b4ffa9d26d52948ffc2ac1974492573e906104c37601a2e9752
MD5 3712b582cb53d40613fad11267aff78b
BLAKE2b-256 1203777c0e557bc19d00d4b2f412cde7c7be93d0804b389bea494e12128e862f

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_decoder-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_decoder-0.29.4-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_decoder-0.29.4-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 65716cd6e554bc319d85e563e10f54283bcdf1aca29d05beff45cb4fbb797c09
MD5 1b112e36b07cb39c89b4b954bdaee1ad
BLAKE2b-256 54ef7cf03123aa2cd407323b3148d2f74628da3ce7ac053b8348503732176f62

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_decoder-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_decoder-0.29.4-cp38-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for edgefirst_decoder-0.29.4-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 72dd9db63e91fa256db674e8c3cf02da37f708c673f1c591ee2b39d4e26eb009
MD5 60b291d4e6d94725d429ae00adc3e03a
BLAKE2b-256 3e8c1fa5c2b80cadead60a385e28e3b1a58b1ba5bdefbf3f4938ab1398bf8977

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for edgefirst_decoder-0.29.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 409a3919e9ad142af8a1651438fef766535bf1adc30ae16b607839af9062bf8d
MD5 15aa6046181b79f6b5eac303a271c1a0
BLAKE2b-256 6726224f4a98104fab8063a5a16856107931527a53731d8815de4c4d4777fd2d

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_decoder-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_decoder-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for edgefirst_decoder-0.29.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 527bcb9b4fe218592d732060e6bea679782d0a7b18be045f9824015f4c4a090d
MD5 4be17c507b7ad68604e6fe8243515d31
BLAKE2b-256 cea9fff5cf7c987e7b220837585988844d2236a70fa97d4655bb0a3e9c09c359

See more details on using hashes here.

Provenance

The following attestation bundles were made for edgefirst_decoder-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_decoder-0.29.4-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for edgefirst_decoder-0.29.4-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7e296d68189618d5ffee3d30ce8b698c4338eace78d42fc6a20a5e787c9ae6ed
MD5 32a903fd3030de7651039bda2a90ea78
BLAKE2b-256 598c6b04b1e02516b9e2b03f6d2a84a44f1043eda057e4e553cb614f42305f53

See more details on using hashes here.

Provenance

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

Pre-release

0.29.0rc1

1 file

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