frus-image 0.6.0

frus — image decoding (PNG/JPEG) into ImageData
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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
// SPDX-License-Identifier: MIT OR Apache-2.0
// Copyright (c) 2026 KalybosPro <kalyboskokou1@gmail.com>

//! `frus-image` — image **decoding** (PNG/JPEG) into [`frus_core::ImageData`], at the
//! file's own size ([`decode`]) or at the size it is shown at ([`decode_at`]).
//!
//! A thin, **optional** layer: `frus-core` is dependency-free and holds nothing but
//! raw pixels; this crate adds the decoder dependency (`image`) to turn file bytes
//! into an `ImageData` ready to upload. Applications use it to load their assets
//! (`decode(include_bytes!("logo.png"))`) without `frus-widgets` or `frus-core`
//! inheriting the decoder's dependency tree.

#![deny(missing_docs)]

// The README's example is compiled and run by `cargo test --doc`, so it cannot rot.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
pub struct ReadmeDoctests;

use std::error::Error;
use std::fmt;

use frus_core::{DecodeSize, ImageData};

/// A decoding failure: an unrecognised format, or corrupt data.
#[derive(Debug)]
pub struct DecodeError(String);

impl DecodeError {
    /// The underlying error message.
    pub fn message(&self) -> &str {
        &self.0
    }
}

impl fmt::Display for DecodeError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "image decoding failed: {}", self.0)
    }
}

impl Error for DecodeError {}

/// Decodes image bytes (PNG or JPEG, the **format being detected** from the magic
/// bytes) into an sRGB RGBA [`ImageData`]. Every image is converted to RGBA8.
///
/// ```
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// // Encode a 2x2 image as PNG, then decode it back.
/// let src = image::RgbaImage::from_pixel(2, 2, image::Rgba([255, 0, 0, 255]));
/// let mut png = Vec::new();
/// image::DynamicImage::ImageRgba8(src)
///     .write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)?;
/// let img = frus_image::decode(&png)?;
/// assert_eq!((img.width(), img.height()), (2, 2));
/// # Ok(()) }
/// ```
pub fn decode(bytes: &[u8]) -> Result<ImageData, DecodeError> {
    let decoded = image::load_from_memory(bytes).map_err(|e| DecodeError(e.to_string()))?;
    let rgba = decoded.to_rgba8();
    let (width, height) = rgba.dimensions();
    Ok(ImageData::from_rgba(width, height, rgba.into_raw()))
}

/// The width and height of the image in `bytes`, read from its header without decoding
/// it: `None` when the format is not one this crate reads, or the header is broken.
///
/// ```
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let src = image::RgbaImage::new(40, 30);
/// let mut png = Vec::new();
/// image::DynamicImage::ImageRgba8(src)
///     .write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)?;
/// assert_eq!(frus_image::dimensions(&png), Some((40, 30)));
/// # Ok(()) }
/// ```
pub fn dimensions(bytes: &[u8]) -> Option<(u32, u32)> {
    image::ImageReader::new(std::io::Cursor::new(bytes))
        .with_guessed_format()
        .ok()?
        .into_dimensions()
        .ok()
}

/// Decodes image bytes **at a size**, smaller than the file's when the place it is shown
/// at needs less: see [`DecodeSize`] for how the size is chosen.
///
/// A JPEG is decoded at 1/2, 1/4 or 1/8 of its size straight from the file, which costs
/// a fraction of a full decode in time and memory, and the rest of the way is a
/// downsampling of that. Any other format is decoded in full, then downsampled **once**,
/// here, rather than on the GPU every frame — the full-size pixels are dropped before
/// this returns.
///
/// ```
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// use frus_core::DecodeSize;
/// let src = image::RgbaImage::from_pixel(400, 300, image::Rgba([0, 128, 255, 255]));
/// let mut png = Vec::new();
/// image::DynamicImage::ImageRgba8(src)
///     .write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)?;
/// let thumb = frus_image::decode_at(&png, DecodeSize::new(Some(100), None))?;
/// assert_eq!((thumb.width(), thumb.height()), (100, 75));
/// # Ok(()) }
/// ```
pub fn decode_at(bytes: &[u8], size: DecodeSize) -> Result<ImageData, DecodeError> {
    if size.is_full() {
        return decode(bytes);
    }
    if bytes.starts_with(&[0xFF, 0xD8]) {
        // A JPEG this decoder cannot scale — a CMYK or a 16-bit one, or one it cannot
        // read at all — takes the general path below.
        if let Some(scaled) = scaled_jpeg(bytes, size) {
            return Ok(scaled);
        }
    }
    let decoded = image::load_from_memory(bytes).map_err(|e| DecodeError(e.to_string()))?;
    let rgba = decoded.to_rgba8();
    drop(decoded);
    let (width, height) = size.target(rgba.width(), rgba.height());
    let rgba = downsample(rgba, width, height);
    Ok(ImageData::from_rgba(width, height, rgba.into_raw()))
}

/// A JPEG decoded at the smallest of its inverse-DCT scales that still covers `size`, and
/// downsampled the rest of the way. `None` when this decoder cannot or need not do it.
fn scaled_jpeg(bytes: &[u8], size: DecodeSize) -> Option<ImageData> {
    let mut decoder = jpeg_decoder::Decoder::new(bytes);
    decoder.read_info().ok()?;
    let info = decoder.info()?;
    let full = (u32::from(info.width), u32::from(info.height));
    let (width, height) = size.target(full.0, full.1);
    if (width, height) == full {
        return None;
    }
    // The decoder takes a scale once *either* side reaches what is asked; asking for a
    // size at the image's own ratio makes that both.
    decoder.scale(width as u16, height as u16).ok()?;
    let pixels = decoder.decode().ok()?;
    let info = decoder.info()?;
    let (scaled_width, scaled_height) = (u32::from(info.width), u32::from(info.height));
    let rgba: Vec<u8> = match info.pixel_format {
        jpeg_decoder::PixelFormat::RGB24 => pixels
            .as_chunks::<3>()
            .0
            .iter()
            .flat_map(|&[r, g, b]| [r, g, b, 255])
            .collect(),
        jpeg_decoder::PixelFormat::L8 => pixels.iter().flat_map(|&l| [l, l, l, 255]).collect(),
        jpeg_decoder::PixelFormat::L16 | jpeg_decoder::PixelFormat::CMYK32 => return None,
    };
    let rgba = image::RgbaImage::from_raw(scaled_width, scaled_height, rgba)?;
    let rgba = downsample(rgba, width, height);
    Some(ImageData::from_rgba(width, height, rgba.into_raw()))
}

/// `rgba` brought down to `width` × `height`, every source pixel counting, so fine detail
/// does not alias.
///
/// A large reduction is mostly **halvings** — each output pixel the mean of four — which
/// are exact for a factor of two and cost one cheap pass each; the filter, as wide as what
/// is left of the reduction, does the last factor of two to four. The filter alone over a
/// twelve-megapixel photograph took 160 ms; the halvings make it a few.
///
/// Translucent pixels are **premultiplied** throughout and divided back at the end: a
/// transparent pixel's colour is not part of the picture, and averaged in as it is it
/// darkens every edge it touches.
fn downsample(rgba: image::RgbaImage, width: u32, height: u32) -> image::RgbaImage {
    if rgba.dimensions() == (width, height) {
        return rgba;
    }
    let translucent = rgba.pixels().any(|p| p[3] < 255);
    let mut img = rgba;
    if translucent {
        for p in img.pixels_mut() {
            let a = u16::from(p[3]);
            for c in 0..3 {
                p[c] = ((u16::from(p[c]) * a + 127) / 255) as u8;
            }
        }
    }
    while img.width() / 2 >= width * 2 && img.height() / 2 >= height * 2 {
        img = halve(&img);
    }
    let mut out =
        image::imageops::resize(&img, width, height, image::imageops::FilterType::Triangle);
    if translucent {
        for p in out.pixels_mut() {
            let a = u16::from(p[3]);
            for c in 0..3 {
                // A fully transparent pixel has no colour to give back, and keeps none.
                if let Some(v) = (u16::from(p[c]) * 255 + a / 2).checked_div(a) {
                    p[c] = v.min(255) as u8;
                }
            }
        }
    }
    out
}

/// Half the size each way, each pixel the mean of the four it covers. An odd last row or
/// column is left out: one pixel in thousands, at the edge.
fn halve(img: &image::RgbaImage) -> image::RgbaImage {
    let (width, height) = (img.width() / 2, img.height() / 2);
    let stride = img.width() as usize * 4;
    let src = img.as_raw();
    let mut out = Vec::with_capacity(width as usize * height as usize * 4);
    for y in 0..height as usize {
        let top = &src[2 * y * stride..][..stride];
        let bottom = &src[(2 * y + 1) * stride..][..stride];
        for x in 0..width as usize {
            let i = x * 8;
            for c in 0..4 {
                let sum = u16::from(top[i + c])
                    + u16::from(top[i + 4 + c])
                    + u16::from(bottom[i + c])
                    + u16::from(bottom[i + 4 + c]);
                out.push(((sum + 2) / 4) as u8);
            }
        }
    }
    image::RgbaImage::from_raw(width, height, out).expect("the size was computed")
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Cursor;

    /// Encodes a test `RgbaImage` in the given format, for a round trip.
    fn encode(img: &image::RgbaImage, format: image::ImageFormat) -> Vec<u8> {
        let mut bytes = Vec::new();
        image::DynamicImage::ImageRgba8(img.clone())
            .write_to(&mut Cursor::new(&mut bytes), format)
            .expect("encoding");
        bytes
    }

    fn sample() -> image::RgbaImage {
        // 4x3, with a red top-left corner and a green bottom-right one.
        let mut img = image::RgbaImage::from_pixel(4, 3, image::Rgba([0, 0, 0, 255]));
        img.put_pixel(0, 0, image::Rgba([255, 0, 0, 255]));
        img.put_pixel(3, 2, image::Rgba([0, 255, 0, 255]));
        img
    }

    #[test]
    fn png_round_trips_pixels_exactly() {
        let png = encode(&sample(), image::ImageFormat::Png);
        let data = decode(&png).expect("PNG decoding");
        assert_eq!((data.width(), data.height()), (4, 3));
        let rgba = data.rgba();
        // Pixel (0,0).
        assert_eq!(&rgba[0..4], &[255, 0, 0, 255]);
        // Pixel (3,2), the last one: offset (2*4 + 3) * 4.
        let last = ((2 * 4 + 3) * 4) as usize;
        assert_eq!(&rgba[last..last + 4], &[0, 255, 0, 255]);
    }

    #[test]
    fn jpeg_decodes_with_correct_dimensions() {
        // JPEG is lossy, so we only check the detected format and the dimensions.
        let jpeg = encode(&sample(), image::ImageFormat::Jpeg);
        let data = decode(&jpeg).expect("JPEG decoding");
        assert_eq!((data.width(), data.height()), (4, 3));
        assert_eq!(data.rgba().len(), 4 * 3 * 4);
    }

    #[test]
    fn format_is_detected_from_magic_bytes() {
        // No format hint is given: detection works from the bytes alone.
        let png = encode(&sample(), image::ImageFormat::Png);
        assert!(png.starts_with(&[0x89, 0x50, 0x4E, 0x47]), "PNG header");
        assert!(decode(&png).is_ok());
    }

    /// A photograph-like test card: a gradient, so a decoder that got the scale or the
    /// order of the pixels wrong shows it.
    fn card(width: u32, height: u32) -> image::RgbaImage {
        image::RgbaImage::from_fn(width, height, |x, y| {
            image::Rgba([(x * 255 / width) as u8, (y * 255 / height) as u8, 128, 255])
        })
    }

    #[test]
    fn a_full_size_decode_at_is_the_plain_decode() {
        let png = encode(&sample(), image::ImageFormat::Png);
        let data = decode_at(&png, DecodeSize::FULL).expect("PNG decoding");
        assert_eq!(data.rgba(), decode(&png).unwrap().rgba());
    }

    #[test]
    fn a_png_is_downsampled_to_the_size_asked() {
        let png = encode(&card(400, 300), image::ImageFormat::Png);
        let data = decode_at(&png, DecodeSize::new(Some(80), Some(80))).unwrap();
        // Covering an 80x80 box at the image's 4:3 ratio.
        assert_eq!((data.width(), data.height()), (107, 80));
        assert_eq!(data.rgba().len(), 107 * 80 * 4);
        // The gradient survives: red grows to the right.
        let red = |x: usize| data.rgba()[(40 * 107 + x) * 4];
        assert!(
            red(5) < red(50) && red(50) < red(100),
            "{} {} {}",
            red(5),
            red(50),
            red(100)
        );
    }

    #[test]
    fn a_jpeg_is_decoded_scaled_to_the_size_asked() {
        let jpeg = encode(&card(1600, 1200), image::ImageFormat::Jpeg);
        let data = decode_at(&jpeg, DecodeSize::new(Some(150), None)).unwrap();
        assert_eq!((data.width(), data.height()), (150, 113));
        // The middle pixel is the middle of the gradient, whatever the scale took.
        let mid = &data.rgba()[(56 * 150 + 75) * 4..][..4];
        assert!((i32::from(mid[0]) - 127).abs() < 12, "{mid:?}");
        assert!((i32::from(mid[1]) - 127).abs() < 12, "{mid:?}");
        assert_eq!(mid[3], 255);
    }

    #[test]
    fn the_scaled_jpeg_path_agrees_with_the_full_one() {
        let jpeg = encode(&card(800, 600), image::ImageFormat::Jpeg);
        let size = DecodeSize::new(Some(100), Some(75));
        let scaled = scaled_jpeg(&jpeg, size).expect("the scaled path takes this JPEG");
        let full = image::load_from_memory(&jpeg).unwrap().to_rgba8();
        let reference = downsample(full, 100, 75);
        let worst = scaled
            .rgba()
            .iter()
            .zip(reference.as_raw())
            .map(|(a, b)| (i32::from(*a) - i32::from(*b)).abs())
            .max()
            .unwrap();
        assert!(worst <= 16, "the two paths differ by {worst}");
    }

    #[test]
    fn a_halving_is_the_mean_of_four() {
        let img = image::RgbaImage::from_fn(5, 3, |x, y| {
            image::Rgba([(x * 40) as u8, (y * 100) as u8, 7, 255])
        });
        let half = halve(&img);
        assert_eq!(half.dimensions(), (2, 1));
        // Columns 2 and 3, rows 0 and 1: red (80+120)/2, green (0+100)/2.
        assert_eq!(half.get_pixel(1, 0).0, [100, 50, 7, 255]);
    }

    #[test]
    fn a_large_reduction_matches_the_filter_alone() {
        let img = card(1200, 900);
        let ours = downsample(img.clone(), 75, 56);
        let filter = image::imageops::resize(&img, 75, 56, image::imageops::FilterType::Triangle);
        let worst = ours
            .as_raw()
            .iter()
            .zip(filter.as_raw())
            .map(|(a, b)| (i32::from(*a) - i32::from(*b)).abs())
            .max()
            .unwrap();
        assert!(worst <= 6, "the halvings moved a pixel by {worst}");
    }

    #[test]
    fn nothing_is_decoded_larger_than_the_file() {
        let png = encode(&sample(), image::ImageFormat::Png);
        let data = decode_at(&png, DecodeSize::new(Some(400), Some(300))).unwrap();
        assert_eq!((data.width(), data.height()), (4, 3));
    }

    #[test]
    fn transparent_pixels_do_not_darken_a_downsampled_edge() {
        // White, half of it fully transparent *black*: averaged unpremultiplied, the
        // visible half's edge turns grey.
        let img = image::RgbaImage::from_fn(64, 64, |x, _| match x < 32 {
            true => image::Rgba([255, 255, 255, 255]),
            false => image::Rgba([0, 0, 0, 0]),
        });
        let png = encode(&img, image::ImageFormat::Png);
        let data = decode_at(&png, DecodeSize::new(Some(8), None)).unwrap();
        // Column 3 of 8 straddles the edge (source columns 24..32 and the filter's reach
        // past them): partly transparent, and still white.
        let p = &data.rgba()[(4 * 8 + 3) * 4..][..4];
        assert!(p[3] > 0 && p[3] < 255, "{p:?}");
        assert!(p[0] >= 250, "a darkened edge: {p:?}");
    }

    #[test]
    fn dimensions_come_from_the_header() {
        let png = encode(&card(64, 48), image::ImageFormat::Png);
        assert_eq!(dimensions(&png), Some((64, 48)));
        let jpeg = encode(&card(64, 48), image::ImageFormat::Jpeg);
        assert_eq!(dimensions(&jpeg), Some((64, 48)));
        assert_eq!(dimensions(b"not an image"), None);
    }

    #[test]
    fn garbage_bytes_error_cleanly() {
        let err = decode(b"not an image at all").unwrap_err();
        assert!(!err.message().is_empty());
        let size = DecodeSize::new(Some(10), None);
        assert!(decode_at(b"not an image at all", size).is_err());
        assert!(decode_at(&[0xFF, 0xD8, 0, 1, 2], size).is_err());
    }
}