tawasuyu/llimphi

1//! `llimphi-image` — decode pipeline para `peniko::Image`.
2//!
3//! Hoy el caller que quiere mostrar una imagen con `View::image()` hace:
4//!
5//! ```ignore
6//! let reader = ImageReader::open(path)?.with_guessed_format()?;
7//! let img = reader.decode()?;
8//! let rgba = img.to_rgba8();
9//! let (w, h) = (rgba.width(), rgba.height());
10//! let blob = Blob::from(rgba.into_raw());
11//! let pen = Image::new(blob, ImageFormat::Rgba8, w, h);
12//! ```
13//!
14//! Cinco líneas + dos llamadas a `?` por cada caller (nahual viewer,
15//! mirada wallpaper, viewer de gallería, etc.). Este crate las
16//! encapsula en dos helpers:
17//!
18//! - [`decode_bytes`] — toma `&[u8]` y devuelve `Result<peniko::Image>`.
19//! - [`load_path`] — toma `&Path` + `max_bytes` cap y devuelve
20//!   `Result<peniko::Image>`, con guardia de tamaño en disco (las apps
21//!   no quieren leer un .iso de 4 GB pensando que es una imagen).
22//!
23//! Con la feature `net` (opt-in, ureq síncrono) se suman descarga + caché por
24//! URL: [`fetch_bytes`]/[`load_url`] (bloqueantes, para correr en un worker) y
25//! [`ImageCache`] (`Clone + Send + Sync`) que la `view` consulta en el hilo UI
26//! mientras un `Handle::spawn` la puebla. El crate base queda sin dep de red.
27//!
28//! `image` (del crate `image`) se construye con `to_rgba8` siempre — la
29//! conversión necesaria para `peniko::ImageFormat::Rgba8`. Para imagen
30//! ya en `rgba8` en memoria (sin necesidad de decodificación), ver
31//! [`from_rgba8`].
32//!
33//! Formatos: los que active la feature del crate `image` upstream (en
34//! el workspace, hoy: PNG, JPEG, WEBP). Otros se pueden habilitar
35//! agregando la feature; el helper no lo limita.
36
37#![forbid(unsafe_code)]
38
39use std::path::Path;
40use std::sync::Arc;
41
42pub use llimphi_raster::peniko::{Blob, ImageAlphaType, ImageBrush as Image, ImageData, ImageFormat};
43
44/// Errores que puede devolver el decode pipeline. Mantenemos el detalle
45/// upstream (`String` con el mensaje del crate `image` o de IO) para no
46/// perder información al cruzar el seam, pero clasificado para que el
47/// caller decida si mostrar diferenciado (`TooBig` ≠ `Decode`).
48#[derive(Debug)]
49pub enum DecodeError {
50    /// IO error leyendo el path (no existe, sin permisos, etc.).
51    Io(std::io::Error),
52    /// El archivo supera el cap `max_bytes` pasado a [`load_path`].
53    TooBig {
54        size_bytes: u64,
55        max_bytes: u64,
56    },
57    /// El reader no reconoce el formato (extensión + magic bytes no
58    /// matchean ninguno activo).
59    UnsupportedFormat,
60    /// El decoder falló (archivo corrupto, formato malo).
61    Decode(String),
62}
63
64impl std::fmt::Display for DecodeError {
65    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
66        match self {
67            DecodeError::Io(e) => write!(f, "IO: {e}"),
68            DecodeError::TooBig { size_bytes, max_bytes } => {
69                write!(f, "archivo demasiado grande: {size_bytes} bytes (cap: {max_bytes})")
70            }
71            DecodeError::UnsupportedFormat => f.write_str("formato no soportado"),
72            DecodeError::Decode(s) => write!(f, "decode: {s}"),
73        }
74    }
75}
76
77impl std::error::Error for DecodeError {}
78
79impl From<std::io::Error> for DecodeError {
80    fn from(e: std::io::Error) -> Self {
81        DecodeError::Io(e)
82    }
83}
84
85/// Construye un `peniko::Image` directamente desde bytes RGBA8 ya
86/// decodificados. No invoca el crate `image`. Útil para imágenes
87/// sintéticas o pre-decodificadas.
88///
89/// El `rgba` debe ser exactamente `w * h * 4` bytes (4 canales). Si
90/// no, el render mostrará basura — el helper no valida porque el
91/// constructor de `peniko::Image` tampoco; queda al caller.
92pub mod perfil;
93pub use perfil::{Curva, Perfil};
94
95/// Una imagen decodificada **más de dónde vino**.
96///
97/// [`decode_bytes`] y [`load_path`] devuelven sólo los píxeles, que es lo que
98/// necesita quien va a pintarlos. Pero un editor no: `tullpu` tiene que poder
99/// abrir una foto Display P3, editarla, y **guardarla de vuelta en P3** en vez
100/// de degradar el archivo del usuario a sRGB por el solo hecho de haberlo
101/// abierto. Para eso hace falta saber en qué espacio venía, y eso es esto.
102pub struct Decodificada {
103    /// Los píxeles, ya en sRGB — idénticos a lo que devuelve [`decode_bytes`].
104    pub imagen: Image,
105    /// El perfil que traía el archivo, si era un matrix-shaper legible.
106    ///
107    /// `None` **no** quiere decir «era sRGB»: quiere decir que no había perfil,
108    /// o que era de los que este crate no entiende (CMYK, LUT). En los dos
109    /// casos los píxeles quedaron como venían y no hay nada a lo que volver.
110    pub origen: Option<Perfil>,
111    /// Si de verdad se recorrieron los píxeles. `false` con `origen: Some(…)`
112    /// es el caso corriente del archivo que ya venía en sRGB.
113    pub convertida: bool,
114}
115
116impl Decodificada {
117    /// Lleva píxeles RGBA8 **de sRGB de vuelta al espacio de origen**, listos
118    /// para escribirlos junto al ICC del archivo. `false` si no hay a dónde
119    /// volver (sin perfil, o el perfil ya era sRGB) — y entonces lo que hay que
120    /// guardar es sRGB, tal cual está.
121    ///
122    /// Ojo con lo que esto **no** deshace: si al abrir se recortó a gamut sRGB
123    /// (ver [`perfil::convertir_desde_srgb`]), ese recorte ya pasó. Lo que
124    /// evita es que el archivo cambie de espacio sin que nadie lo pidiera.
125    pub fn devolver_al_origen(&self, rgba: &mut [u8]) -> bool {
126        match &self.origen {
127            Some(p) => perfil::convertir_desde_srgb(rgba, p),
128            None => false,
129        }
130    }
131}
132
133pub fn from_rgba8(rgba: Vec<u8>, w: u32, h: u32) -> Image {
134    let blob = Blob::new(Arc::new(rgba));
135    Image::new(ImageData {
136        data: blob,
137        format: ImageFormat::Rgba8,
138        alpha_type: ImageAlphaType::Alpha,
139        width: w,
140        height: h,
141    })
142}
143
144/// Decodifica **y lleva la imagen a sRGB** si trae un perfil ICC que diga otra
145/// cosa.
146///
147/// Se baja al decoder en vez de llamar a `reader.decode()` para poder
148/// preguntarle el perfil: `decode()` lo consume y lo tira. Sin esto, una foto
149/// Display P3 —lo que saca cualquier teléfono desde 2016— se pinta
150/// **sobresaturada**, porque sus rojos, que son más rojos que los de sRGB, se
151/// muestran como si fueran los de sRGB.
152fn decodificar_con_perfil<'a, R: std::io::BufRead + std::io::Seek + 'a>(
153    reader: image::ImageReader<R>,
154) -> Result<Decodificada, DecodeError> {
155    use image::ImageDecoder as _;
156    let mut decoder = reader
157        .into_decoder()
158        .map_err(|e| DecodeError::Decode(e.to_string()))?;
159    let icc = decoder.icc_profile().ok().flatten();
160    let img = image::DynamicImage::from_decoder(decoder)
161        .map_err(|e| DecodeError::Decode(e.to_string()))?;
162    let rgba = img.to_rgba8();
163    let (w, h) = (rgba.width(), rgba.height());
164    let mut datos = rgba.into_raw();
165    // Sin perfil se asume sRGB, que es la convención de la web y lo que se hacía
166    // antes. Con un perfil sRGB, `convertir_a_srgb` detecta que la matriz es la
167    // identidad y no recorre un solo píxel.
168    let origen = icc.as_deref().and_then(perfil::leer_icc);
169    let convertida = match &origen {
170        Some(p) => perfil::convertir_a_srgb(&mut datos, p),
171        None => false,
172    };
173    Ok(Decodificada { imagen: from_rgba8(datos, w, h), origen, convertida })
174}
175
176/// Decodifica bytes a un `peniko::Image` listo para `View::image()`.
177/// El crate `image` adivina el formato por magic bytes (no por
178/// extensión) — apto para data URIs, descargas, blobs de DB.
179pub fn decode_bytes(bytes: &[u8]) -> Result<Image, DecodeError> {
180    decode_bytes_con_origen(bytes).map(|d| d.imagen)
181}
182
183/// Igual que [`decode_bytes`], pero además dice **de qué espacio de color
184/// venía**. Para editores que tienen que re-exportar al espacio de origen; el
185/// que sólo va a pintar usa [`decode_bytes`] y no se entera.
186pub fn decode_bytes_con_origen(bytes: &[u8]) -> Result<Decodificada, DecodeError> {
187    let reader = image::ImageReader::new(std::io::Cursor::new(bytes))
188        .with_guessed_format()
189        .map_err(DecodeError::Io)?;
190    if reader.format().is_none() {
191        return Err(DecodeError::UnsupportedFormat);
192    }
193    decodificar_con_perfil(reader)
194}
195
196/// Lee un path, valida tamaño en disco, decodifica. El cap se compara
197/// contra el tamaño del archivo (NO la imagen decodificada, que en
198/// RGBA8 puede ser mucho mayor — un PNG 4K decomprimido ocupa ~64 MB).
199/// `max_bytes = 0` deshabilita el cap.
200pub fn load_path(path: &Path, max_bytes: u64) -> Result<Image, DecodeError> {
201    load_path_con_origen(path, max_bytes).map(|d| d.imagen)
202}
203
204/// Igual que [`load_path`], pero además dice de qué espacio de color venía.
205/// Ver [`Decodificada`].
206pub fn load_path_con_origen(path: &Path, max_bytes: u64) -> Result<Decodificada, DecodeError> {
207    if max_bytes > 0 {
208        let meta = std::fs::metadata(path).map_err(DecodeError::Io)?;
209        if meta.len() > max_bytes {
210            return Err(DecodeError::TooBig {
211                size_bytes: meta.len(),
212                max_bytes,
213            });
214        }
215    }
216    let reader = image::ImageReader::open(path)
217        .map_err(DecodeError::Io)?
218        .with_guessed_format()
219        .map_err(DecodeError::Io)?;
220    if reader.format().is_none() {
221        return Err(DecodeError::UnsupportedFormat);
222    }
223    decodificar_con_perfil(reader)
224}
225
226/// Descarga + caché de imágenes por URL (feature `net`). Síncrono (ureq):
227/// la idea es que la app lo llame desde un worker (`Handle::spawn` /
228/// `std::thread`), NO en el hilo de UI, y despache un `Msg` con la imagen
229/// decodificada. La [`ImageCache`] es `Clone + Send + Sync` (interna
230/// `Arc<Mutex<…>>`) para compartirse entre el hilo UI (lecturas) y los
231/// workers (descargas).
232#[cfg(feature = "net")]
233mod net {
234    use super::{decode_bytes, DecodeError, Image};
235    use std::collections::HashMap;
236    use std::io::Read;
237    use std::sync::{Arc, Mutex};
238
239    /// Errores de [`fetch_bytes`]/[`load_url`].
240    #[derive(Debug)]
241    pub enum FetchError {
242        /// La capa de red/HTTP falló (DNS, TLS, status no-2xx, timeout…).
243        Network(String),
244        /// El cuerpo descargado superó `max_bytes`.
245        TooBig { max_bytes: u64 },
246        /// Se descargó pero no se pudo decodificar como imagen.
247        Decode(DecodeError),
248    }
249
250    impl std::fmt::Display for FetchError {
251        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
252            match self {
253                FetchError::Network(s) => write!(f, "red: {s}"),
254                FetchError::TooBig { max_bytes } => {
255                    write!(f, "descarga supera el cap de {max_bytes} bytes")
256                }
257                FetchError::Decode(e) => write!(f, "{e}"),
258            }
259        }
260    }
261
262    impl std::error::Error for FetchError {}
263
264    impl From<DecodeError> for FetchError {
265        fn from(e: DecodeError) -> Self {
266            FetchError::Decode(e)
267        }
268    }
269
270    /// Descarga los bytes crudos de una URL (bloqueante). `max_bytes = 0`
271    /// deshabilita el cap; si no, corta la lectura apenas se excede (no
272    /// bufferiza un cuerpo gigante antes de rechazarlo).
273    pub fn fetch_bytes(url: &str, max_bytes: u64) -> Result<Vec<u8>, FetchError> {
274        let resp = ureq::get(url)
275            .call()
276            .map_err(|e| FetchError::Network(e.to_string()))?;
277        let mut reader = resp.into_reader();
278        let mut buf = Vec::new();
279        if max_bytes > 0 {
280            // Leemos hasta max_bytes+1: si llega a +1 sabemos que se pasó.
281            reader
282                .by_ref()
283                .take(max_bytes + 1)
284                .read_to_end(&mut buf)
285                .map_err(|e| FetchError::Network(e.to_string()))?;
286            if buf.len() as u64 > max_bytes {
287                return Err(FetchError::TooBig { max_bytes });
288            }
289        } else {
290            reader
291                .read_to_end(&mut buf)
292                .map_err(|e| FetchError::Network(e.to_string()))?;
293        }
294        Ok(buf)
295    }
296
297    /// Descarga + decodifica una URL a `peniko::Image` (bloqueante). Sin
298    /// caché — para eso usar [`ImageCache::get_or_fetch`].
299    pub fn load_url(url: &str, max_bytes: u64) -> Result<Image, FetchError> {
300        let bytes = fetch_bytes(url, max_bytes)?;
301        Ok(decode_bytes(&bytes)?)
302    }
303
304    /// Techo de imágenes vivas en la caché. Sin cota, `get_or_fetch` acumulaba
305    /// toda `Image` descargada durante la sesión (p. ej. navegar resultados de
306    /// media-tube) sin evictar nunca — fuga monótona de RAM. `get` re-descarga
307    /// si una URL fue evictada, así que evictar la más vieja es transparente.
308    pub(crate) const CACHE_CAP: usize = 256;
309
310    /// Caché de imágenes por URL, compartible entre hilos. La `peniko::Image`
311    /// es barata de clonar (su `Blob` es `Arc`-backed), así que `get` devuelve
312    /// una copia lista para `View::image()`. Evicción FIFO al superar
313    /// `CACHE_CAP`: `order` lleva el orden de inserción de claves nuevas, en
314    /// paso con `inner`.
315    #[derive(Clone, Default)]
316    pub struct ImageCache {
317        inner: Arc<Mutex<HashMap<String, Image>>>,
318        order: Arc<Mutex<std::collections::VecDeque<String>>>,
319    }
320
321    impl ImageCache {
322        pub fn new() -> Self {
323            Self::default()
324        }
325
326        /// Imagen cacheada para esa URL, si ya se descargó. Barato — esto es
327        /// lo que la `view` consulta en el hilo UI cada frame.
328        pub fn get(&self, url: &str) -> Option<Image> {
329            self.inner.lock().ok()?.get(url).cloned()
330        }
331
332        /// `true` si la URL ya está en caché (sin clonar la imagen).
333        pub fn contains(&self, url: &str) -> bool {
334            self.inner
335                .lock()
336                .map(|m| m.contains_key(url))
337                .unwrap_or(false)
338        }
339
340        /// Inserta (o reemplaza) la imagen de una URL. Lo llama el worker tras
341        /// decodificar, o la app si ya tiene la imagen por otra vía. Evicta la
342        /// más vieja (FIFO) al superar `CACHE_CAP`.
343        pub fn insert(&self, url: impl Into<String>, img: Image) {
344            let url = url.into();
345            if let Ok(mut m) = self.inner.lock() {
346                let es_nueva = !m.contains_key(&url);
347                m.insert(url.clone(), img);
348                if es_nueva {
349                    if let Ok(mut order) = self.order.lock() {
350                        order.push_back(url);
351                        while m.len() > CACHE_CAP {
352                            match order.pop_front() {
353                                Some(vieja) => {
354                                    m.remove(&vieja);
355                                }
356                                None => break,
357                            }
358                        }
359                    }
360                }
361            }
362        }
363
364        /// Vacía la caché (p. ej. al cambiar de sesión/usuario).
365        pub fn clear(&self) {
366            if let Ok(mut m) = self.inner.lock() {
367                m.clear();
368            }
369            if let Ok(mut order) = self.order.lock() {
370                order.clear();
371            }
372        }
373
374        /// Cantidad de imágenes cacheadas.
375        pub fn len(&self) -> usize {
376            self.inner.lock().map(|m| m.len()).unwrap_or(0)
377        }
378
379        pub fn is_empty(&self) -> bool {
380            self.len() == 0
381        }
382
383        /// Devuelve la imagen cacheada o, si falta, la descarga+decodifica y la
384        /// cachea (bloqueante). **Llamar desde un worker**, no en el hilo UI.
385        /// El patrón típico: la `view` hace `cache.get(url)`; si es `None`,
386        /// dispara `Handle::spawn` que llama `get_or_fetch` y al volver
387        /// despacha un `Msg` para repintar.
388        pub fn get_or_fetch(&self, url: &str, max_bytes: u64) -> Result<Image, FetchError> {
389            if let Some(img) = self.get(url) {
390                return Ok(img);
391            }
392            let img = load_url(url, max_bytes)?;
393            self.insert(url.to_string(), img.clone());
394            Ok(img)
395        }
396    }
397}
398
399#[cfg(feature = "net")]
400pub use net::{fetch_bytes, load_url, FetchError, ImageCache};
401
402#[cfg(test)]
403mod tests {
404    use super::*;
405
406    /// Bytes PNG válido de 2×2 píxeles: rojo, verde, azul, blanco.
407    /// Generado con `image::RgbaImage` + encode a PNG.
408    fn png_2x2_bytes() -> Vec<u8> {
409        let mut buf = Vec::new();
410        let mut rgba = image::RgbaImage::new(2, 2);
411        rgba.put_pixel(0, 0, image::Rgba([255, 0, 0, 255]));
412        rgba.put_pixel(1, 0, image::Rgba([0, 255, 0, 255]));
413        rgba.put_pixel(0, 1, image::Rgba([0, 0, 255, 255]));
414        rgba.put_pixel(1, 1, image::Rgba([255, 255, 255, 255]));
415        image::DynamicImage::ImageRgba8(rgba)
416            .write_to(&mut std::io::Cursor::new(&mut buf), image::ImageFormat::Png)
417            .expect("encode png");
418        buf
419    }
420
421    #[cfg(feature = "net")]
422    #[test]
423    fn image_cache_evicta_fifo_al_superar_el_cap() {
424        // Inserta más del cap: las más viejas se evictan, las últimas viven.
425        let cache = ImageCache::new();
426        let total = net::CACHE_CAP + 10;
427        for i in 0..total {
428            cache.insert(format!("u{i}"), from_rgba8(vec![0u8; 4], 1, 1));
429        }
430        assert_eq!(cache.len(), net::CACHE_CAP, "la caché queda acotada al cap");
431        // Las primeras 10 (las más viejas) fueron evictadas.
432        assert!(cache.get("u0").is_none());
433        assert!(cache.get("u9").is_none());
434        // Las últimas siguen presentes.
435        assert!(cache.get(&format!("u{}", total - 1)).is_some());
436        // Reinsertar una clave existente no reordena ni evicta de más.
437        cache.insert(format!("u{}", total - 1), from_rgba8(vec![0u8; 4], 1, 1));
438        assert_eq!(cache.len(), net::CACHE_CAP);
439    }
440
441    #[test]
442    fn from_rgba8_arma_image_con_dimensiones_correctas() {
443        let img = from_rgba8(vec![0u8; 16], 2, 2); // 2x2x4 = 16 bytes
444        assert_eq!(img.image.width, 2);
445        assert_eq!(img.image.height, 2);
446        assert!(matches!(img.image.format, ImageFormat::Rgba8));
447    }
448
449    #[test]
450    fn decode_bytes_png_basico() {
451        let bytes = png_2x2_bytes();
452        let img = decode_bytes(&bytes).expect("decode ok");
453        assert_eq!(img.image.width, 2);
454        assert_eq!(img.image.height, 2);
455    }
456
457    #[test]
458    fn decode_bytes_invalido_devuelve_error() {
459        let bad = vec![0u8, 1, 2, 3, 4, 5];
460        let r = decode_bytes(&bad);
461        assert!(r.is_err());
462        // Magic no matchea ningún formato conocido → UnsupportedFormat.
463        match r.unwrap_err() {
464            DecodeError::UnsupportedFormat => {}
465            other => panic!("esperaba UnsupportedFormat, recibí: {other:?}"),
466        }
467    }
468
469    #[test]
470    fn load_path_respeta_cap_de_tamano() {
471        // Escribimos un PNG válido y lo cargamos con cap muy bajo.
472        let dir = std::env::temp_dir();
473        let path = dir.join("llimphi_image_test_cap.png");
474        let bytes = png_2x2_bytes();
475        std::fs::write(&path, &bytes).expect("write tmp png");
476        // Cap de 1 byte → demasiado grande.
477        let r = load_path(&path, 1);
478        match r {
479            Err(DecodeError::TooBig { size_bytes, max_bytes }) => {
480                assert!(size_bytes > 1);
481                assert_eq!(max_bytes, 1);
482            }
483            other => panic!("esperaba TooBig, recibí: {other:?}"),
484        }
485        // Cap 0 → deshabilitado, decodifica OK.
486        let img = load_path(&path, 0).expect("decode ok sin cap");
487        assert_eq!(img.image.width, 2);
488        assert_eq!(img.image.height, 2);
489        std::fs::remove_file(&path).ok();
490    }
491
492    #[test]
493    fn load_path_io_error_cuando_no_existe() {
494        let r = load_path(std::path::Path::new("/no/existe/probablemente.png"), 0);
495        match r {
496            Err(DecodeError::Io(_)) => {}
497            other => panic!("esperaba Io, recibí: {other:?}"),
498        }
499    }
500
501    /// La lógica de caché (sin red): insert / get / contains / clear sobre una
502    /// imagen sintética. La descarga real no se testea (requiere red).
503    #[cfg(feature = "net")]
504    #[test]
505    fn image_cache_insert_get_contains_clear() {
506        let cache = ImageCache::new();
507        assert!(cache.is_empty());
508        assert!(!cache.contains("http://x/a.png"));
509        assert!(cache.get("http://x/a.png").is_none());
510
511        let img = from_rgba8(vec![0u8; 16], 2, 2);
512        cache.insert("http://x/a.png", img);
513        assert!(cache.contains("http://x/a.png"));
514        assert_eq!(cache.len(), 1);
515        let got = cache.get("http://x/a.png").expect("cacheada");
516        assert_eq!(got.image.width, 2);
517
518        // Una segunda URL no colisiona.
519        cache.insert("http://x/b.png".to_string(), from_rgba8(vec![0u8; 4], 1, 1));
520        assert_eq!(cache.len(), 2);
521
522        cache.clear();
523        assert!(cache.is_empty());
524    }
525}