Skip to main content

qualia_core_db/hypermedia_authoring/
image.rs

1//! Image editing — layers, brushes, selection, filters, masks, colour, vector.
2//!
3//! ~40 required functions. This module provides the data structures and
4//! deterministic operations for image editing.
5
6use std::collections::BTreeMap;
7#[path = "image_source_over.rs"]
8mod source_over;
9#[path = "image_filters.rs"]
10mod filters;
11#[path = "image_composite.rs"]
12mod composite;
13pub use filters::{filter_plan, filter_rgba8_into};
14pub use composite::{composite_into, validate_document};
15
16#[derive(Clone, Copy, Debug, PartialEq, Eq)]
17pub enum ImageError { Dimensions, Storage, Parameters, Budget, Output, Scratch }
18impl std::fmt::Display for ImageError {
19    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "image operation: {self:?}") }
20}
21impl std::error::Error for ImageError {}
22#[derive(Clone, Copy, Debug)]
23pub struct ImageLimits { pub max_pixels: usize, pub max_work: usize, pub max_bytes: usize }
24impl Default for ImageLimits {
25    fn default() -> Self { Self { max_pixels:4*1024*1024, max_work:1024*1024*1024, max_bytes:256*1024*1024 } }
26}
27#[derive(Clone, Copy, Debug, PartialEq)]
28pub enum ImageFilterOp {
29    GaussianBlur { sigma:f32 }, Sharpen { sigma:f32, amount:f32 },
30    HueRotate { degrees:f32 }, Emboss { azimuth_degrees:f32, strength:f32 },
31}
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub struct FilterPlan { pub scratch_pixels:usize, pub work:usize, pub bytes:usize }
34/// Cold checked adapter. All admission precedes allocation and source mutation.
35pub fn try_apply_image_filter(layer:&mut ImageLayer, op:ImageFilterOp, limits:ImageLimits)->Result<(),ImageError> {
36    let plan=filter_plan(layer.width,layer.height,op,limits)?;
37    let count=(layer.width as usize).checked_mul(layer.height as usize).ok_or(ImageError::Dimensions)?;
38    if layer.pixels.len()!=count {return Err(ImageError::Storage);}
39    let mut output=Vec::new(); output.try_reserve_exact(count).map_err(|_|ImageError::Budget)?;
40    output.resize(count,[0;4]);
41    let mut scratch=Vec::new(); scratch.try_reserve_exact(plan.scratch_pixels).map_err(|_|ImageError::Budget)?;
42    scratch.resize(plan.scratch_pixels,[0.0;4]);
43    filter_rgba8_into(&layer.pixels,layer.width,layer.height,op,limits,&mut output,&mut scratch)?;
44    layer.pixels=output;
45    Ok(())
46}
47
48
49/// Blend mode for layer compositing.
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51pub enum BlendMode {
52    Normal,
53    Multiply,
54    Screen,
55    Overlay,
56    SoftLight,
57    HardLight,
58    ColorDodge,
59    ColorBurn,
60    Difference,
61    Exclusion,
62}
63
64/// A layer in an image document.
65#[derive(Debug, Clone)]
66pub struct ImageLayer {
67    pub id: String,
68    pub name: String,
69    pub width: u32,
70    pub height: u32,
71    pub pixels: Vec<[u8; 4]>, // RGBA
72    pub opacity: f32,
73    pub blend_mode: BlendMode,
74    pub visible: bool,
75    pub offset_x: i32,
76    pub offset_y: i32,
77    pub mask: Option<Vec<u8>>,
78}
79
80impl ImageLayer {
81    /// Creates a `width`x`height` layer with transparent pixels, full opacity, Normal blend, and zero offset.
82    pub fn new(id: &str, name: &str, width: u32, height: u32) -> Self {
83        Self {
84            id: id.to_string(),
85            name: name.to_string(),
86            width,
87            height,
88            pixels: vec![[0, 0, 0, 0]; (width as usize) * (height as usize)],
89            opacity: 1.0,
90            blend_mode: BlendMode::Normal,
91            visible: true,
92            offset_x: 0,
93            offset_y: 0,
94            mask: None,
95        }
96    }
97
98    /// Sets the RGBA pixel at `(x,y)` — no-op when out of bounds.
99    pub fn set_pixel(&mut self, x: u32, y: u32, rgba: [u8; 4]) {
100        if x < self.width && y < self.height {
101            let idx = (y as usize) * (self.width as usize) + (x as usize);
102            self.pixels[idx] = rgba;
103        }
104    }
105
106    /// RGBA pixel at `(x,y)`; transparent `[0;4]` when out of bounds.
107    pub fn get_pixel(&self, x: u32, y: u32) -> [u8; 4] {
108        if x < self.width && y < self.height {
109            let idx = (y as usize) * (self.width as usize) + (x as usize);
110            self.pixels[idx]
111        } else {
112            [0, 0, 0, 0]
113        }
114    }
115
116    /// Fills the whole layer with `rgba`.
117    pub fn fill(&mut self, rgba: [u8; 4]) {
118        for px in &mut self.pixels {
119            *px = rgba;
120        }
121    }
122
123    /// Sets layer opacity (callers supply 0..1).
124    pub fn set_opacity(&mut self, opacity: f32) {
125        self.opacity = opacity.clamp(0.0, 1.0);
126    }
127
128    /// Sets the layer blend mode.
129    pub fn set_blend_mode(&mut self, mode: BlendMode) {
130        self.blend_mode = mode;
131    }
132
133    /// Toggles layer visibility.
134    pub fn set_visible(&mut self, visible: bool) {
135        self.visible = visible;
136    }
137
138    /// Sets the layer pixel offset within the document.
139    pub fn set_offset(&mut self, x: i32, y: i32) {
140        self.offset_x = x;
141        self.offset_y = y;
142    }
143
144    /// Apply a rectangular selection mask.
145    pub fn set_rect_mask(&mut self, x: u32, y: u32, w: u32, h: u32) {
146        let mut mask = vec![0u8; (self.width as usize) * (self.height as usize)];
147        for my in y..y.saturating_add(h).min(self.height) {
148            for mx in x..x.saturating_add(w).min(self.width) {
149                let idx = (my as usize) * (self.width as usize) + (mx as usize);
150                mask[idx] = 255;
151            }
152        }
153        self.mask = Some(mask);
154    }
155
156    /// Removes the layer mask.
157    pub fn clear_mask(&mut self) {
158        self.mask = None;
159    }
160}
161
162/// A brush stroke — sequence of points with size and colour.
163#[derive(Debug, Clone)]
164pub struct BrushStroke {
165    pub points: Vec<(f32, f32)>, // (x, y)
166    pub size: f32,
167    pub colour: [u8; 4],
168    pub opacity: f32,
169    pub hardness: f32,
170}
171
172impl BrushStroke {
173    /// Creates a stroke with `size` and `colour` and an empty point list.
174    pub fn new(size: f32, colour: [u8; 4]) -> Self {
175        Self {
176            points: Vec::new(),
177            size,
178            colour,
179            opacity: 1.0,
180            hardness: 0.8,
181        }
182    }
183
184    /// Appends a point to the stroke path.
185    pub fn add_point(&mut self, x: f32, y: f32) {
186        self.points.push((x, y));
187    }
188
189    /// Apply the brush stroke to a layer.
190    pub fn apply_to(&self, layer: &mut ImageLayer) {
191        let radius = self.size / 2.0;
192        for &(px, py) in &self.points {
193            let x0 = (px - radius).max(0.0) as u32;
194            let y0 = (py - radius).max(0.0) as u32;
195            let x1 = ((px + radius) as u32).min(layer.width);
196            let y1 = ((py + radius) as u32).min(layer.height);
197            for y in y0..y1 {
198                for x in x0..x1 {
199                    let dx = x as f32 - px;
200                    let dy = y as f32 - py;
201                    let dist = (dx * dx + dy * dy).sqrt();
202                    if dist <= radius {
203                        let alpha = if dist <= radius * self.hardness {
204                            self.opacity
205                        } else {
206                            self.opacity
207                                * (1.0
208                                    - (dist - radius * self.hardness)
209                                        / (radius * (1.0 - self.hardness)))
210                        };
211                        let pixel = source_over::rgba(self.colour, layer.get_pixel(x, y), alpha);
212                        layer.set_pixel(x, y, pixel);
213                    }
214                }
215            }
216        }
217    }
218}
219
220/// A selection region.
221#[derive(Debug, Clone)]
222pub struct Selection {
223    pub id: String,
224    pub shape: SelectionShape,
225    pub feather: f32,
226}
227
228#[derive(Debug, Clone)]
229pub enum SelectionShape {
230    Rectangle {
231        x: u32,
232        y: u32,
233        width: u32,
234        height: u32,
235    },
236    Ellipse {
237        cx: f32,
238        cy: f32,
239        rx: f32,
240        ry: f32,
241    },
242    Lasso {
243        points: Vec<(f32, f32)>,
244    },
245}
246
247/// Image filter type.
248#[derive(Debug, Clone, Copy, PartialEq, Eq)]
249pub enum ImageFilter {
250    GaussianBlur,
251    Sharpen,
252    Grayscale,
253    Invert,
254    Sepia,
255    Brightness,
256    Contrast,
257    HueRotate,
258    EdgeDetect,
259    Emboss,
260}
261
262/// Legacy normalized-intensity convenience operation on a valid bounded layer.
263/// Completed mappings: blur sigma=4*i; sharpen sigma=1/amount=i; hue=360*i
264/// degrees; emboss azimuth=135 degrees/strength=i. Other operations retain their
265/// established semantics. Use try_apply_image_filter for typed, fallible edits.
266/// Panics on malformed/out-of-budget input for the four completed mappings.
267pub fn apply_filter(layer: &mut ImageLayer, filter: ImageFilter, intensity: f32) {
268    let intensity = intensity.clamp(0.0, 1.0);
269    let completed = match filter {
270        ImageFilter::GaussianBlur => Some(ImageFilterOp::GaussianBlur {sigma:4.0*intensity}),
271        ImageFilter::Sharpen => Some(ImageFilterOp::Sharpen {sigma:1.0,amount:intensity}),
272        ImageFilter::HueRotate => Some(ImageFilterOp::HueRotate {degrees:360.0*intensity}),
273        ImageFilter::Emboss => Some(ImageFilterOp::Emboss {azimuth_degrees:135.0,strength:intensity}),
274        _ => None,
275    };
276    if let Some(op)=completed {
277        try_apply_image_filter(layer,op,ImageLimits::default())
278            .expect("legacy apply_filter requires valid bounded input; use checked image APIs for fallible admission");
279        return;
280    }
281    match filter {
282        ImageFilter::Grayscale => {
283            for px in &mut layer.pixels {
284                let gray = (px[0] as u32 * 299 + px[1] as u32 * 587 + px[2] as u32 * 114) / 1000;
285                px[0] = gray as u8;
286                px[1] = gray as u8;
287                px[2] = gray as u8;
288            }
289        }
290        ImageFilter::Invert => {
291            for px in &mut layer.pixels {
292                px[0] = 255 - px[0];
293                px[1] = 255 - px[1];
294                px[2] = 255 - px[2];
295            }
296        }
297        ImageFilter::Sepia => {
298            for px in &mut layer.pixels {
299                let r = px[0] as f32;
300                let g = px[1] as f32;
301                let b = px[2] as f32;
302                let nr = (0.393 * r + 0.769 * g + 0.189 * b).min(255.0);
303                let ng = (0.349 * r + 0.686 * g + 0.168 * b).min(255.0);
304                let nb = (0.272 * r + 0.534 * g + 0.131 * b).min(255.0);
305                px[0] = (nr * intensity + r * (1.0 - intensity)) as u8;
306                px[1] = (ng * intensity + g * (1.0 - intensity)) as u8;
307                px[2] = (nb * intensity + b * (1.0 - intensity)) as u8;
308            }
309        }
310        ImageFilter::Brightness => {
311            let delta = (intensity * 100.0) as i32;
312            for px in &mut layer.pixels {
313                px[0] = (px[0] as i32 + delta).clamp(0, 255) as u8;
314                px[1] = (px[1] as i32 + delta).clamp(0, 255) as u8;
315                px[2] = (px[2] as i32 + delta).clamp(0, 255) as u8;
316            }
317        }
318        ImageFilter::Contrast => {
319            let factor = 1.0 + intensity;
320            for px in &mut layer.pixels {
321                px[0] = (((px[0] as f32 - 128.0) * factor) + 128.0).clamp(0.0, 255.0) as u8;
322                px[1] = (((px[1] as f32 - 128.0) * factor) + 128.0).clamp(0.0, 255.0) as u8;
323                px[2] = (((px[2] as f32 - 128.0) * factor) + 128.0).clamp(0.0, 255.0) as u8;
324            }
325        }
326        ImageFilter::EdgeDetect => {
327            // Simple Sobel edge detection.
328            let w = layer.width as usize;
329            let h = layer.height as usize;
330            let original = layer.pixels.clone();
331            for y in 1..h - 1 {
332                for x in 1..w - 1 {
333                    let idx = y * w + x;
334                    let p = |offset: usize| original[offset][0] as i32;
335                    let gx = -p(idx - w - 1) - 2 * p(idx - 1) - p(idx + w - 1)
336                        + p(idx - w + 1)
337                        + 2 * p(idx + 1)
338                        + p(idx + w + 1);
339                    let gy = -p(idx - w - 1) - 2 * p(idx - w) - p(idx - w + 1)
340                        + p(idx + w - 1)
341                        + 2 * p(idx + w)
342                        + p(idx + w + 1);
343                    let mag = ((gx * gx + gy * gy) as f32).sqrt().min(255.0) as u8;
344                    let val = (mag as f32 * intensity) as u8;
345                    layer.pixels[idx] = [val, val, val, original[idx][3]];
346                }
347            }
348        }
349        ImageFilter::GaussianBlur | ImageFilter::Sharpen | ImageFilter::HueRotate | ImageFilter::Emboss => unreachable!("completed filters returned above"),
350    }
351}
352
353/// An image document with multiple layers.
354#[derive(Debug, Clone)]
355pub struct ImageDocument {
356    pub id: String,
357    pub width: u32,
358    pub height: u32,
359    pub layers: Vec<ImageLayer>,
360    pub active_layer: usize,
361    pub selections: BTreeMap<String, Selection>,
362}
363
364impl ImageDocument {
365    /// Creates a `width`x`height` document with one default layer.
366    pub fn new(id: &str, width: u32, height: u32) -> Self {
367        Self {
368            id: id.to_string(),
369            width,
370            height,
371            layers: Vec::new(),
372            active_layer: 0,
373            selections: BTreeMap::new(),
374        }
375    }
376
377    /// Appends a layer named `name` and makes it active; returns it mutably.
378    pub fn add_layer(&mut self, name: &str) -> &mut ImageLayer {
379        let id = format!("layer_{}", self.layers.len());
380        let layer = ImageLayer::new(&id, name, self.width, self.height);
381        self.layers.push(layer);
382        self.active_layer = self.layers.len() - 1;
383        self.layers.last_mut().unwrap()
384    }
385
386    /// Removes layer `index`; `false` when out of range.
387    pub fn remove_layer(&mut self, index: usize) -> bool {
388        if index < self.layers.len() {
389            self.layers.remove(index);
390            if self.active_layer >= self.layers.len() && !self.layers.is_empty() {
391                self.active_layer = self.layers.len() - 1;
392            }
393            true
394        } else {
395            false
396        }
397    }
398
399    /// Mutable access to the active layer, or `None`.
400    pub fn active_layer_mut(&mut self) -> Option<&mut ImageLayer> {
401        self.layers.get_mut(self.active_layer)
402    }
403
404    /// Number of layers.
405    pub fn layer_count(&self) -> usize {
406        self.layers.len()
407    }
408
409    /// Fallible, bounded cold authoring composition. Source layers remain immutable.
410    pub fn try_composite(&self, limits:ImageLimits)->Result<Vec<[u8;4]>,ImageError> {
411        let count=validate_document(self,limits)?;
412        let mut output=Vec::new(); output.try_reserve_exact(count).map_err(|_|ImageError::Budget)?;
413        output.resize(count,[0;4]);
414        composite_into(self,&mut output,limits)?;
415        Ok(output)
416    }
417    /// Caller-buffered composition; admission finishes before any output changes.
418    pub fn composite_into(&self,out:&mut[[u8;4]],limits:ImageLimits)->Result<(),ImageError> {
419        composite_into(self,out,limits)
420    }
421    /// Composite valid layers with their blend modes, masks and signed placement.
422    /// # Panics
423    /// A malformed/out-of-budget legacy document panics before producing output.
424    /// Use try_composite or composite_into for explicit non-panicking refusal.
425    pub fn composite(&self)->Vec<[u8;4]> {
426        self.try_composite(ImageLimits::default()).expect("invalid legacy image document; use checked composition for fallible admission")
427    }
428
429    /// Adds a selection region.
430    pub fn add_selection(&mut self, selection: Selection) {
431        self.selections.insert(selection.id.clone(), selection);
432    }
433
434    /// Clears all selection regions.
435    pub fn clear_selections(&mut self) {
436        self.selections.clear();
437    }
438}
439
440#[cfg(test)]
441mod tests {
442    use super::*;
443
444    #[test]
445    fn layer_creation() {
446        let layer = ImageLayer::new("l1", "Background", 100, 100);
447        assert_eq!(layer.width, 100);
448        assert_eq!(layer.pixels.len(), 10000);
449        assert!(layer.visible);
450    }
451
452    #[test]
453    fn layer_set_pixel() {
454        let mut layer = ImageLayer::new("l1", "test", 10, 10);
455        layer.set_pixel(5, 5, [255, 0, 0, 255]);
456        assert_eq!(layer.get_pixel(5, 5), [255, 0, 0, 255]);
457    }
458
459    #[test]
460    fn layer_fill() {
461        let mut layer = ImageLayer::new("l1", "test", 10, 10);
462        layer.fill([128, 64, 32, 255]);
463        assert_eq!(layer.get_pixel(0, 0), [128, 64, 32, 255]);
464    }
465
466    #[test]
467    fn brush_stroke_apply() {
468        let mut layer = ImageLayer::new("l1", "test", 50, 50);
469        let mut stroke = BrushStroke::new(10.0, [255, 0, 0, 255]);
470        stroke.add_point(25.0, 25.0);
471        stroke.apply_to(&mut layer);
472        // Center pixel should be red.
473        let px = layer.get_pixel(25, 25);
474        assert!(px[0] > 200);
475    }
476
477    #[test]
478    fn filter_grayscale() {
479        let mut layer = ImageLayer::new("l1", "test", 10, 10);
480        layer.fill([255, 0, 0, 255]);
481        apply_filter(&mut layer, ImageFilter::Grayscale, 1.0);
482        let px = layer.get_pixel(0, 0);
483        // Gray should be ~76 (0.299 * 255).
484        assert!((px[0] as i32 - 76).abs() < 2);
485        assert_eq!(px[0], px[1]);
486        assert_eq!(px[1], px[2]);
487    }
488
489    #[test]
490    fn filter_invert() {
491        let mut layer = ImageLayer::new("l1", "test", 10, 10);
492        layer.fill([100, 50, 200, 255]);
493        apply_filter(&mut layer, ImageFilter::Invert, 1.0);
494        let px = layer.get_pixel(0, 0);
495        assert_eq!(px[0], 155);
496        assert_eq!(px[1], 205);
497        assert_eq!(px[2], 55);
498    }
499
500    #[test]
501    fn filter_brightness() {
502        let mut layer = ImageLayer::new("l1", "test", 10, 10);
503        layer.fill([100, 100, 100, 255]);
504        apply_filter(&mut layer, ImageFilter::Brightness, 0.5);
505        let px = layer.get_pixel(0, 0);
506        assert!(px[0] > 100);
507    }
508
509    #[test]
510    fn document_add_layer() {
511        let mut doc = ImageDocument::new("doc1", 100, 100);
512        doc.add_layer("Background");
513        doc.add_layer("Foreground");
514        assert_eq!(doc.layer_count(), 2);
515    }
516
517    #[test]
518    fn document_composite() {
519        let mut doc = ImageDocument::new("doc1", 10, 10);
520        let bg = doc.add_layer("bg");
521        bg.fill([0, 0, 255, 255]);
522        let fg = doc.add_layer("fg");
523        fg.fill([255, 0, 0, 128]);
524        let composite = doc.composite();
525        // Should be a blend of blue and red.
526        assert!(composite[0][0] > 0);
527        assert!(composite[0][2] > 0);
528    }
529
530    #[test]
531    fn document_remove_layer() {
532        let mut doc = ImageDocument::new("doc1", 10, 10);
533        doc.add_layer("bg");
534        doc.add_layer("fg");
535        assert!(doc.remove_layer(0));
536        assert_eq!(doc.layer_count(), 1);
537    }
538
539    #[test]
540    fn layer_mask() {
541        let mut layer = ImageLayer::new("l1", "test", 20, 20);
542        layer.set_rect_mask(5, 5, 10, 10);
543        assert!(layer.mask.is_some());
544        let mask = layer.mask.as_ref().unwrap();
545        // Center should be 255, corners should be 0.
546        assert_eq!(mask[10 * 20 + 10], 255);
547        assert_eq!(mask[0], 0);
548    }
549
550    #[test]
551    fn filter_edge_detect() {
552        let mut layer = ImageLayer::new("l1", "test", 10, 10);
553        // Create a sharp edge: left half white, right half black.
554        for y in 0..10 {
555            for x in 0..10 {
556                if x < 5 {
557                    layer.set_pixel(x, y, [255, 255, 255, 255]);
558                }
559            }
560        }
561        apply_filter(&mut layer, ImageFilter::EdgeDetect, 1.0);
562        // Edge should be detected around x=4-5.
563        let edge_px = layer.get_pixel(4, 5);
564        assert!(edge_px[0] > 0);
565    }
566}