edgefirst-hal 0.13.2

EdgeFirst Hardware Abstraction Layer for edge AI inference pipelines
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

# edgefirst-hal

[![Crates.io](https://img.shields.io/crates/v/edgefirst-hal.svg)](https://crates.io/crates/edgefirst-hal)
[![Documentation](https://docs.rs/edgefirst-hal/badge.svg)](https://docs.rs/edgefirst-hal)
[![License](https://img.shields.io/crates/l/edgefirst-hal.svg)](LICENSE)

**EdgeFirst Hardware Abstraction Layer** — a unified Rust library for edge AI inference pipelines.

This is the umbrella crate that re-exports the core EdgeFirst HAL components:

- [`edgefirst-tensor`](https://crates.io/crates/edgefirst-tensor) — Zero-copy tensor memory management (DMA, SHM, PBO, system memory)
- [`edgefirst-image`](https://crates.io/crates/edgefirst-image) — Hardware-accelerated image processing and format conversion
- [`edgefirst-decoder`](https://crates.io/crates/edgefirst-decoder) — ML model output decoding (YOLOv5/v8/v11/v26, ModelPack)
- [`edgefirst-tracker`](https://crates.io/crates/edgefirst-tracker) — Multi-object tracking (ByteTrack)

## Features

- **Zero-copy memory management** with DMA-BUF, POSIX shared memory, and PBO support
- **Hardware-accelerated image processing** via OpenGL, G2D (NXP i.MX), and optimized CPU
- **Efficient ML post-processing** for object detection and segmentation models
- **Int8 GPU shaders** for direct signed int8 output without CPU post-processing
- **Cross-platform** — Linux (with hardware acceleration), macOS, and other Unix systems

## Quick Start

```rust,ignore
use edgefirst_image::{load_image, ImageProcessor, ImageProcessorTrait, Rotation, Flip, Crop};
use edgefirst_tensor::{PixelFormat, DType};

// Load a source image
let bytes = std::fs::read("image.jpg")?;
let input = load_image(&bytes, Some(PixelFormat::Rgb), None)?;

// Create an image processor (auto-selects best backend)
let mut processor = ImageProcessor::new()?;

// Allocate a GPU-optimal output buffer — always use create_image() for
// destinations passed to convert(). This selects the best memory type
// (DMA-buf, PBO, or system memory) for zero-copy GPU paths.
let mut output = processor.create_image(640, 640, PixelFormat::Rgb, DType::U8, None)?;

// Convert with letterbox resize
processor.convert(&input, &mut output, Rotation::None, Flip::None, Crop::default())?;
```

> **Why `create_image()`?** Creating tensors directly with `Tensor::new()` or
> `TensorDyn::image()` bypasses GPU memory negotiation. The processor cannot
> allocate PBO-backed buffers without knowing the GL context. Use `create_image()`
> for any tensor that will be passed to `convert()`.

## Platform Support

| Platform | Memory Types | Image Acceleration |
|----------|--------------|-------------------|
| Linux (NXP i.MX8/i.MX95) | DMA, SHM, PBO, Mem | OpenGL, G2D, CPU |
| Linux (other) | SHM, PBO, Mem | OpenGL, CPU |
| macOS | Mem | CPU |
| Other Unix | SHM, Mem | CPU |

## Python Bindings

This library is also available as a Python package:

```bash
pip install edgefirst-hal
```

See [`edgefirst-hal` on PyPI](https://pypi.org/project/edgefirst-hal/) for
Python-specific documentation.

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/EdgeFirstAI/hal/blob/main/LICENSE) for details.

## Links

- [EdgeFirst AI](https://edgefirst.ai)
- [GitHub Repository](https://github.com/EdgeFirstAI/hal)
- [API Documentation](https://docs.rs/edgefirst-hal)
- [Python Package](https://pypi.org/project/edgefirst-hal/)