otf-pixels-core 0.2.0

Core engine for otf-pixels: op graph, descriptors, tiles, codec traits, evaluator.
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

<div align="center">

# otf-pixels-core

***The engine under Pixels: graph, tiles, scheduler***

[crates.io](https://crates.io/crates/otf-pixels-core) | [Docs](https://docs.rs/otf-pixels-core) | [Pixels](https://github.com/Open-Tech-Foundation/Pixels)

</div>

<div align="right">

*An [Open Tech Foundation](https://opentechf.org/) project*

</div>

> An image is a node in an immutable, lazy graph. The scheduler pulls output
> tiles through it on demand, on one shared pool of worker threads.

> [!TIP]
> **Building an app or a server?** Use [`otf-pixels`](https://crates.io/crates/otf-pixels) instead:
> it wraps this engine in a chainable API with every codec and op wired in.

## Use it

Depend on this crate to write a codec or an op. A codec implements `Decoder`
(rows out) and `Encoder` (rows in):

```rust
use otf_pixels_core::{Decoder, ImageDescriptor, PixelFormat, Result};

/// A decoder for a flat grey image.
#[derive(Debug)]
struct Grey(ImageDescriptor);

impl Decoder for Grey {
    fn descriptor(&self) -> ImageDescriptor {
        self.0
    }
    fn read_row(&mut self, out: &mut [u8]) -> Result<()> {
        out.fill(128);
        Ok(())
    }
}

let grey = Grey(ImageDescriptor::new(640, 480, PixelFormat::Rgb8)?);
let png = otf_pixels::Image::from_decoder(Box::new(grey), otf_pixels::Format::Raw)
    .output(otf_pixels::Format::Png, Default::default())
    .bytes()?;
```

## API

| Item | Purpose |
| --- | --- |
| `Image`, `Node` | The lazy graph: `apply` an op, `combine` several inputs |
| `Decoder`, `Encoder`, `Codec` | The codec contracts: rows out, rows in, magic-byte probe |
| `Op`, `Producer`, `AccessPattern` | The op contract: output shape, input demand, per-tile compute |
| `Scheduler`, `SchedulerOptions` | Tile evaluation; `Scheduler::global()` is the shared default |
| `ImageDescriptor`, `PixelFormat`, `Region` | Shape, pixel layout and rectangles |
| `Tile`, `TileBuf`, `TileMut` | The pixel buffers ops read and write |
| `Source`, `Sink` | Streaming input and output; any `Read` / `Write` qualifies |
| `Limits`, `PixelsError`, `ErrorCode` | Input limits and the error taxonomy |
| `evaluate` | The whole-image reference evaluator the scheduler is tested against |

## Part of Pixels

| Crate | Role |
| --- | --- |
| [`otf-pixels`](https://crates.io/crates/otf-pixels) | The chainable `Image` API most users want |
| [`otf-pixels-core`](https://crates.io/crates/otf-pixels-core) | Graph, tiles, scheduler, codec and op traits |
| [`otf-pixels-ops`](https://crates.io/crates/otf-pixels-ops) | Image operations |
| [`otf-pixels-compress`](https://crates.io/crates/otf-pixels-compress) | DEFLATE, zlib, LZW, checksums |
| `otf-pixels-codec-*` | One crate per format |

## License

Apache-2.0 — see [LICENSE](https://github.com/Open-Tech-Foundation/Pixels/blob/main/LICENSE).