oxedyne/fe2o3/fe2o3_graphics/src/pdf_colour.rs
10.4 KiB, 27 runs
created by r1870400018:69461, which is this file's identity for as long as the history lasts, whatever it is later renamed to
download · who wrote it · its history
| 1 | //! How the PDF writer sets a colour, and the colours it converts. |
| 2 | //! |
| 3 | //! A [`ColourOut`] says what a file holds. `Native` writes each ink in its own space and `Rgb` lowers |
| 4 | //! every ink to sRGB, which is what every file written before an ink knew its space holds. `Cmyk` and |
| 5 | //! `Grey` convert: each fill, stroke and text colour reaches the file in the output space, and each |
| 6 | //! colour raster is taken as sRGB and converted through an ICC [`Transform`], so that nothing in the file is |
| 7 | //! written as `rg`, `RG` or `/DeviceRGB`. |
| 8 | //! |
| 9 | //! A `/DeviceGray` value is a subset of every output space, as Ghostscript keeps it: a grey ink, and a raster |
| 10 | //! whose source held grey alone, reach a grey output unchanged. |
| 11 | //! |
| 12 | //! # Black |
| 13 | //! |
| 14 | //! Under [`Black::KOnly`] a grey ink, and an RGB ink whose three channels are equal, is written as `g` |
| 15 | //! or `G`, which a CMYK device prints with the black ink alone, so that text and rules set in black |
| 16 | //! carry no cyan, magenta or yellow. [`Black::Rich`] sends the same inks through the transform, which |
| 17 | //! gives the profile's own rich black. A CMYK ink is kept as it is under `Cmyk`. A raster from a grey source |
| 18 | //! ([`Tone::Grey`]) is written as `/DeviceGray` under K only and goes through the transform under a rich black, |
| 19 | //! as a grey ink does. |
| 20 | //! |
| 21 | //! # Images |
| 22 | //! |
| 23 | //! A converted image is held by the identity of its samples and of the transform that made it, in a |
| 24 | //! cache the writer shares with every writer cloned from the same [`ColourOut`]. A watch builds one |
| 25 | //! per settings load, so a figure unchanged between two compiles is converted once. The cache is held |
| 26 | //! to a budget of bytes, and drops the image least recently read when a new one would pass it. |
| 27 | //! |
| 28 | //! [Written with AI entirely](https://need2know.ai/entirely-ai/code)\ |
| 29 | //! Anthropic Claude |
| 30 | |
| 31 | use crate::colour::Ink; |
| 32 | use crate::icc::transform::Transform; |
| 33 | use crate::pixmap::Tone; |
| 34 | |
| 35 | use oxedyne_fe2o3_core::prelude::*; |
| 36 | use oxedyne_fe2o3_hash::fingerprint::{ |
| 37 | Fingerprint, |
| 38 | Fingerprinter, |
| 39 | }; |
| 40 | |
| 41 | use std::collections::HashMap; |
| 42 | use std::sync::{ |
| 43 | Arc, |
| 44 | Mutex, |
| 45 | }; |
| 46 | |
| 47 | // The bytes of converted samples a cache holds before it drops the least recently read. |
| 48 | const BUDGET: usize = 128 << 20; |
| 49 | |
| 50 | // Pixels converted at a time, so that a large raster never holds its whole result as floats. |
| 51 | const CHUNK: usize = 1 << 16; |
| 52 | |
| 53 | // The inks one page converts before its memo is emptied. |
| 54 | const MEMO: usize = 256; |
| 55 | |
| 56 | #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] |
| 57 | pub enum Black { |
| 58 | #[default] |
| 59 | KOnly, |
| 60 | Rich, |
| 61 | } |
| 62 | |
| 63 | /// How the writer sets a colour. `Rgb` lowers every ink to sRGB and writes `rg` and `RG`, the bytes a |
| 64 | /// file carried before an ink knew its space; `Native` writes each ink in its own space, `g` for a |
| 65 | /// grey, `k` for a CMYK and `rg` for the rest, and the same for the stroke forms. `Cmyk` and `Grey` |
| 66 | /// convert every colour to the output space. |
| 67 | #[derive(Clone, Debug, Default)] |
| 68 | pub enum ColourOut { |
| 69 | Native, |
| 70 | #[default] |
| 71 | Rgb, |
| 72 | Cmyk { |
| 73 | xf: Arc<Transform>, // sRGB (or the RGB profile) to the CMYK profile |
| 74 | black: Black, |
| 75 | images: ImageCache, |
| 76 | }, |
| 77 | Grey { |
| 78 | xf: Arc<Transform>, // sRGB (or the RGB profile) to the grey profile |
| 79 | cmyk: Arc<Transform>, // the CMYK profile to the grey profile, for a CMYK ink |
| 80 | images: ImageCache, |
| 81 | }, |
| 82 | } |
| 83 | |
| 84 | // Two modes are equal when they write the same file: the transforms are compared by identity, and a cache is |
| 85 | // no part of what is written. |
| 86 | impl PartialEq for ColourOut { |
| 87 | fn eq(&self, other: &Self) -> bool { |
| 88 | match (self, other) { |
| 89 | (Self::Native, Self::Native) => true, |
| 90 | (Self::Rgb, Self::Rgb) => true, |
| 91 | (Self::Cmyk { xf: a, black: p, .. }, Self::Cmyk { xf: b, black: q, .. }) |
| 92 | => a.id() == b.id() && p == q, |
| 93 | (Self::Grey { xf: a, cmyk: p, .. }, Self::Grey { xf: b, cmyk: q, .. }) |
| 94 | => a.id() == b.id() && p.id() == q.id(), |
| 95 | _ => false, |
| 96 | } |
| 97 | } |
| 98 | } |
| 99 | |
| 100 | impl Eq for ColourOut {} |
| 101 | |
| 102 | impl ColourOut { |
| 103 | |
| 104 | /// A CMYK output through `xf`, which takes RGB to CMYK, with a cache of its own for images. |
| 105 | pub fn cmyk(xf: Arc<Transform>, black: Black) -> Outcome<Self> { |
| 106 | res!(xf.rgb_to_cmyk([0.0; 3])); |
| 107 | Ok(Self::Cmyk { xf, black, images: ImageCache::default() }) |
| 108 | } |
| 109 | |
| 110 | /// A grey output through `xf`, which takes RGB to grey, and `cmyk`, which takes CMYK to grey. |
| 111 | pub fn grey(xf: Arc<Transform>, cmyk: Arc<Transform>) -> Outcome<Self> { |
| 112 | res!(xf.rgb_to_grey([0.0; 3])); |
| 113 | res!(cmyk.cmyk_to_grey([0.0; 4])); |
| 114 | Ok(Self::Grey { xf, cmyk, images: ImageCache::default() }) |
| 115 | } |
| 116 | |
| 117 | /// Does this mode convert colours, rather than write them as they come? |
| 118 | pub fn converts(&self) -> bool { |
| 119 | matches!(self, Self::Cmyk { .. } | Self::Grey { .. }) |
| 120 | } |
| 121 | |
| 122 | /// The colour space a converting mode names for each page's transparency group. |
| 123 | pub fn group_space(&self) -> Option<&'static str> { |
| 124 | match self { |
| 125 | Self::Cmyk { .. } => Some("DeviceCMYK"), |
| 126 | Self::Grey { .. } => Some("DeviceGray"), |
| 127 | _ => None, |
| 128 | } |
| 129 | } |
| 130 | |
| 131 | /// The cache of converted images, none in a mode that writes images as they come. |
| 132 | pub fn images(&self) -> Option<&ImageCache> { |
| 133 | match self { |
| 134 | Self::Cmyk { images, .. } | Self::Grey { images, .. } => Some(images), |
| 135 | _ => None, |
| 136 | } |
| 137 | } |
| 138 | |
| 139 | /// The ink as this mode writes it. Under `Rgb` an ink is lowered to sRGB, and under `Cmyk` and `Grey` it |
| 140 | /// is converted: the result is grey or CMYK, never RGB. |
| 141 | pub fn ink(&self, ink: Ink) -> Outcome<Ink> { |
| 142 | Ok(match self { |
| 143 | Self::Native => ink, |
| 144 | Self::Rgb => Ink::Rgb(ink.to_rgba()), |
| 145 | Self::Cmyk { xf, black, .. } => match ink { |
| 146 | Ink::Cmyk { .. } => ink, |
| 147 | Ink::Grey { .. } if *black == Black::KOnly => ink, |
| 148 | Ink::Rgb(c) if *black == Black::KOnly && c.r == c.g && c.g == c.b |
| 149 | => Ink::Grey { v: c.r as f32 / 255.0, a: c.a }, |
| 150 | _ => { |
| 151 | let k = res!(xf.rgb_to_cmyk(rgb_of(ink))); |
| 152 | Ink::Cmyk { c: k[0], m: k[1], y: k[2], k: k[3], a: ink.alpha() } |
| 153 | }, |
| 154 | }, |
| 155 | Self::Grey { xf, cmyk, .. } => match ink { |
| 156 | Ink::Grey { .. } => ink, |
| 157 | Ink::Cmyk { c, m, y, k, a } => { |
| 158 | let v = res!(cmyk.cmyk_to_grey([c as f64, m as f64, y as f64, k as f64])); |
| 159 | Ink::Grey { v, a } |
| 160 | }, |
| 161 | _ => Ink::Grey { v: res!(xf.rgb_to_grey(rgb_of(ink))), a: ink.alpha() }, |
| 162 | }, |
| 163 | }) |
| 164 | } |
| 165 | |
| 166 | /// Converts a raster of packed 8-bit sRGB, returning its channel count and its samples, or none in a mode that |
| 167 | /// writes a raster as it comes. A raster seen before, through the same transform, is read from the cache. A |
| 168 | /// raster of `Tone::Grey`, whose three samples are equal, is kept as one channel of grey except under a rich |
| 169 | /// black. |
| 170 | pub fn image(&self, rgb: &[u8], iw: usize, ih: usize, tone: Tone) -> Outcome<Option<(usize, Arc<Vec<u8>>)>> { |
| 171 | let (xf, images, chans, keep) = match self { |
| 172 | Self::Cmyk { xf, images, black } => (xf, images, 4, *black == Black::KOnly), |
| 173 | Self::Grey { xf, images, .. } => (xf, images, 1, true), |
| 174 | _ => return Ok(None), |
| 175 | }; |
| 176 | if rgb.len() != iw * ih * 3 { |
| 177 | return Err(err!( |
| 178 | "An image of {} by {} samples holds {} bytes of RGB, not the {} it should.", |
| 179 | iw, ih, rgb.len(), iw * ih * 3; Invalid, Input, Size)); |
| 180 | } |
| 181 | if tone == Tone::Grey && keep { |
| 182 | return Ok(Some((1, Arc::new(rgb.iter().step_by(3).copied().collect())))); |
| 183 | } |
| 184 | let mut f = Fingerprinter::new(); |
| 185 | f.write_usize(iw); |
| 186 | f.write_usize(ih); |
| 187 | f.write(rgb); |
| 188 | let key = (f.finish(), xf.id()); |
| 189 | if let Some(hit) = res!(images.get(&key)) { |
| 190 | return Ok(Some((chans, hit))); |
| 191 | } |
| 192 | let grid = res!(xf.grid()); |
| 193 | let mut out = Vec::with_capacity(iw * ih * chans); |
| 194 | for part in rgb.chunks(CHUNK * 3) { |
| 195 | for px in res!(grid.convert8(part)) { |
| 196 | for c in &px[..chans] { |
| 197 | out.push((c.clamp(0.0, 1.0) * 255.0 + 0.5) as u8); |
| 198 | } |
| 199 | } |
| 200 | } |
| 201 | let out = Arc::new(out); |
| 202 | res!(images.put(key, out.clone())); |
| 203 | Ok(Some((chans, out))) |
| 204 | } |
| 205 | } |
| 206 | |
| 207 | // The colour as fractions of full scale in sRGB, for an ink that is not CMYK. |
| 208 | fn rgb_of(ink: Ink) -> [f64; 3] { |
| 209 | let c = ink.to_rgba(); |
| 210 | [c.r as f64 / 255.0, c.g as f64 / 255.0, c.b as f64 / 255.0] |
| 211 | } |
| 212 | |
| 213 | /// The inks of one page as the mode writes them, each converted once. A document sets thousands of glyphs |
| 214 | /// in a handful of colours, so a conversion through the profiles is looked up rather than made again. |
| 215 | pub(crate) struct Inks<'a> { |
| 216 | out: &'a ColourOut, |
| 217 | memo: HashMap<Ink, Ink>, |
| 218 | } |
| 219 | |
| 220 | impl<'a> Inks<'a> { |
| 221 | |
| 222 | pub(crate) fn new(out: &'a ColourOut) -> Self { |
| 223 | Self { out, memo: HashMap::new() } |
| 224 | } |
| 225 | |
| 226 | pub(crate) fn get(&mut self, ink: Ink) -> Outcome<Ink> { |
| 227 | if !self.out.converts() { |
| 228 | return self.out.ink(ink); |
| 229 | } |
| 230 | if let Some(done) = self.memo.get(&ink) { |
| 231 | return Ok(*done); |
| 232 | } |
| 233 | let done = res!(self.out.ink(ink)); |
| 234 | if self.memo.len() >= MEMO { |
| 235 | self.memo.clear(); |
| 236 | } |
| 237 | self.memo.insert(ink, done); |
| 238 | Ok(done) |
| 239 | } |
| 240 | } |
| 241 | |
| 242 | type Key = (Fingerprint, u64); // the samples and size, then the transform |
| 243 | |
| 244 | #[derive(Debug)] |
| 245 | struct Entry { |
| 246 | data: Arc<Vec<u8>>, |
| 247 | read: u64, // the tick of the last read, for dropping the least recent |
| 248 | } |
| 249 | |
| 250 | #[derive(Debug, Default)] |
| 251 | struct Held { |
| 252 | map: HashMap<Key, Entry>, |
| 253 | bytes: usize, |
| 254 | tick: u64, |
| 255 | hits: u64, |
| 256 | misses: u64, |
| 257 | } |
| 258 | |
| 259 | /// What a cache holds and has done. |
| 260 | #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] |
| 261 | pub struct CacheStats { |
| 262 | pub hits: u64, |
| 263 | pub misses: u64, |
| 264 | pub held: usize, // images |
| 265 | pub bytes: usize, // of converted samples |
| 266 | } |
| 267 | |
| 268 | /// Converted samples, shared by every clone of the handle. |
| 269 | #[derive(Clone, Debug, Default)] |
| 270 | pub struct ImageCache { |
| 271 | held: Arc<Mutex<Held>>, |
| 272 | } |
| 273 | |
| 274 | impl ImageCache { |
| 275 | |
| 276 | /// What the cache holds, and how often it has been asked for what it held and for what it did not. |
| 277 | pub fn stats(&self) -> Outcome<CacheStats> { |
| 278 | let h = lock_mutex!(self.held); |
| 279 | Ok(CacheStats { hits: h.hits, misses: h.misses, held: h.map.len(), bytes: h.bytes }) |
| 280 | } |
| 281 | |
| 282 | fn get(&self, key: &Key) -> Outcome<Option<Arc<Vec<u8>>>> { |
| 283 | let mut h = lock_mutex!(self.held); |
| 284 | h.tick += 1; |
| 285 | let tick = h.tick; |
| 286 | let found = h.map.get_mut(key).map(|e| { |
| 287 | e.read = tick; |
| 288 | e.data.clone() |
| 289 | }); |
| 290 | match found { |
| 291 | Some(_) => h.hits += 1, |
| 292 | None => h.misses += 1, |
| 293 | } |
| 294 | Ok(found) |
| 295 | } |
| 296 | |
| 297 | fn put(&self, key: Key, data: Arc<Vec<u8>>) -> Outcome<()> { |
| 298 | let mut h = lock_mutex!(self.held); |
| 299 | h.tick += 1; |
| 300 | let tick = h.tick; |
| 301 | let size = data.len(); |
| 302 | if let Some(old) = h.map.insert(key, Entry { data, read: tick }) { |
| 303 | h.bytes -= old.data.len(); |
| 304 | } |
| 305 | h.bytes += size; |
| 306 | // An image larger than the whole budget is held alone, as the only one the next compile can reuse. |
| 307 | while h.bytes > BUDGET && h.map.len() > 1 { |
| 308 | let oldest = h.map.iter().filter(|(k, _)| **k != key).min_by_key(|(_, e)| e.read).map(|(k, _)| *k); |
| 309 | match oldest { |
| 310 | Some(k) => { |
| 311 | if let Some(gone) = h.map.remove(&k) { |
| 312 | h.bytes -= gone.data.len(); |
| 313 | } |
| 314 | }, |
| 315 | None => break, |
| 316 | } |
| 317 | } |
| 318 | Ok(()) |
| 319 | } |
| 320 | } |