Oregami
Repositories/oxedyne/fe2o3

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
31use crate::colour::Ink;
32use crate::icc::transform::Transform;
33use crate::pixmap::Tone;
34
35use oxedyne_fe2o3_core::prelude::*;
36use oxedyne_fe2o3_hash::fingerprint::{
37 Fingerprint,
38 Fingerprinter,
39};
40
41use std::collections::HashMap;
42use std::sync::{
43 Arc,
44 Mutex,
45};
46
47// The bytes of converted samples a cache holds before it drops the least recently read.
48const BUDGET: usize = 128 << 20;
49
50// Pixels converted at a time, so that a large raster never holds its whole result as floats.
51const CHUNK: usize = 1 << 16;
52
53// The inks one page converts before its memo is emptied.
54const MEMO: usize = 256;
55
56#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
57pub 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)]
68pub 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.
86impl 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
100impl Eq for ColourOut {}
101
102impl 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.
208fn 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.
215pub(crate) struct Inks<'a> {
216 out: &'a ColourOut,
217 memo: HashMap<Ink, Ink>,
218}
219
220impl<'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
242type Key = (Fingerprint, u64); // the samples and size, then the transform
243
244#[derive(Debug)]
245struct 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)]
251struct 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)]
261pub 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)]
270pub struct ImageCache {
271 held: Arc<Mutex<Held>>,
272}
273
274impl 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}