1use std::io::Cursor;
12use std::sync::Arc;
13
14use alpha2_model::{LinearPrimaries, ProviderSource};
15use alpha2_time::MediaTime;
16use exr::block::reader::ChunksReader as _;
17use exr::meta::attribute::{ChannelDescription, ChannelList, SampleType};
18use half::f16;
19
20use crate::api::{
21 ColorOrigin, Diagnostic, ExtensionError, Format, FramePixels, LinearColor, ProbeReport,
22 ResourceResolver, Timing, VisualFrame, VisualProvider, VisualSource,
23};
24use crate::budget::{MAX_CANVAS_PIXELS, check_canvas};
25
26const MAGIC: [u8; 4] = [0x76, 0x2f, 0x31, 0x01];
27
28pub(crate) fn is_exr(bytes: &[u8]) -> bool {
29 bytes.starts_with(&MAGIC)
30}
31
32pub struct ExrProvider;
34
35impl VisualProvider for ExrProvider {
36 fn name(&self) -> &'static str {
37 "exr"
38 }
39
40 fn probe(&self, bytes: &[u8]) -> Option<Result<ProbeReport, ExtensionError>> {
41 is_exr(bytes).then(|| decode_exr(bytes, None).map(|image| still_report(&image)))
42 }
43
44 fn open(
45 &self,
46 bytes: Arc<[u8]>,
47 source: &ProviderSource,
48 _resolver: &dyn ResourceResolver,
49 ) -> Result<Box<dyn VisualSource>, ExtensionError> {
50 let ProviderSource::Exr { primaries } = source else {
51 return Err(ExtensionError::Mismatch("not an OpenEXR source".into()));
52 };
53 if !is_exr(&bytes) {
54 return Err(ExtensionError::Mismatch("not an OpenEXR file".into()));
55 }
56 let image = decode_exr(&bytes, primaries.map(project_color))?;
57 let report = still_report(&image);
58 Ok(Box::new(ExrSource {
59 report,
60 frame: VisualFrame {
61 width: image.width,
62 height: image.height,
63 pixels: FramePixels::LinearF16(image.pixels.into()),
64 index: 0,
65 start: MediaTime::from_ticks(i64::MIN),
66 end: None,
67 diagnostics: Vec::new(),
68 },
69 }))
70 }
71}
72
73fn still_report(image: &ExrImage) -> ProbeReport {
74 ProbeReport {
75 format: Format::Exr,
76 width: image.width,
77 height: image.height,
78 timing: Timing::Static,
79 loop_count: None,
80 items: Vec::new(),
81 item: None,
82 color: Some(image.color.clone()),
83 diagnostics: image.diagnostics.clone(),
84 }
85}
86
87struct ExrSource {
88 report: ProbeReport,
89 frame: VisualFrame,
90}
91
92impl VisualSource for ExrSource {
93 fn report(&self) -> &ProbeReport {
94 &self.report
95 }
96
97 fn render(
98 &mut self,
99 _time: MediaTime,
100 _fit: (u32, u32),
101 ) -> Result<VisualFrame, ExtensionError> {
102 Ok(self.frame.clone())
103 }
104
105 fn resident_bytes(&self) -> usize {
106 self.frame.pixels.byte_len()
107 }
108}
109
110pub(crate) struct ExrImage {
111 pub(crate) width: u32,
112 pub(crate) height: u32,
113 pub(crate) pixels: Vec<u16>,
115 pub(crate) color: LinearColor,
116 pub(crate) diagnostics: Vec<Diagnostic>,
117}
118
119pub(crate) fn project_color(primaries: LinearPrimaries) -> LinearColor {
120 LinearColor {
121 primaries: Some(primaries),
122 chromaticities: named_chromaticities(primaries),
123 origin: ColorOrigin::Project,
124 }
125}
126
127pub(crate) fn decode_exr(
130 bytes: &[u8],
131 color: Option<LinearColor>,
132) -> Result<ExrImage, ExtensionError> {
133 check_channel_lists(bytes)?;
134 let reader = exr::block::read(Cursor::new(bytes), false).map_err(exr_error)?;
135 let headers = reader.headers();
136 if headers.iter().all(|header| header.deep) {
137 return Err(ExtensionError::Unsupported(
138 "deep OpenEXR data is not supported".into(),
139 ));
140 }
141 let Some(part) = headers.iter().position(|header| {
142 !header.deep
143 && channels_shown(header.channels.list.iter().map(|c| c.name.to_string())).is_some()
144 }) else {
145 let names = headers
146 .iter()
147 .flat_map(|header| {
148 header
149 .channels
150 .list
151 .iter()
152 .map(|channel| channel.name.to_string())
153 })
154 .collect::<Vec<_>>()
155 .join(", ");
156 return Err(ExtensionError::Unsupported(format!(
157 "no part has R, G, and B channels or a Y channel (it has {names})"
158 )));
159 };
160 let header = headers[part].clone();
161 let display = header.shared_attributes.display_window;
162 let (width, height) = (
163 u32::try_from(display.size.x()).unwrap_or(u32::MAX),
164 u32::try_from(display.size.y()).unwrap_or(u32::MAX),
165 );
166 let mut diagnostics = check_part(&header, width, height, part, headers.len())?;
167 let color = color.unwrap_or_else(|| {
168 let declared = file_color(header.shared_attributes.chromaticities);
169 if defines_color_space(declared.chromaticities) {
170 return declared;
171 }
172 diagnostics.push(Diagnostic::UnsupportedFeature {
174 feature: "chromaticities that define no color space".into(),
175 path: "/chromaticities".into(),
176 count: 1,
177 });
178 file_color(None)
179 });
180
181 let channels = &header.channels.list;
182 let shown = channels_shown(channels.iter().map(|channel| channel.name.to_string()))
183 .ok_or_else(|| ExtensionError::Malformed("the part's channels could not be read".into()))?;
184 let others = (0..channels.len())
185 .filter(|index| !shown.contains(&Some(*index)))
186 .collect::<Vec<_>>();
187 if let Some(first) = others.first() {
188 diagnostics.push(Diagnostic::UnsupportedFeature {
189 feature: "channels besides R, G, B, A, and Y".into(),
190 path: format!("/channels/{}", channels[*first].name),
191 count: others.len(),
192 });
193 }
194 for channel in shown.iter().flatten().map(|index| &channels[*index]) {
195 check_channel(channel)?;
196 }
197 if shown
198 .iter()
199 .flatten()
200 .any(|index| channels[*index].sample_type == SampleType::F32)
201 {
202 diagnostics.push(Diagnostic::ReducedPrecision);
203 }
204
205 let matrix = to_bt709(color.chromaticities);
206 let mut canvas = Canvas::new(&header, display, (width, height), shown, matrix);
207 reader
208 .filter_chunks(false, |_, tile, block| {
209 block.layer == part && tile.is_largest_resolution_level()
210 })
211 .map_err(exr_error)?
212 .decompress_sequential(false, |_, block| {
213 canvas.place_block(&block, &header.channels);
214 Ok(())
215 })
216 .map_err(exr_error)?;
217 let Canvas { pixels, counts, .. } = canvas;
218 if counts.non_finite > 0 {
219 diagnostics.push(Diagnostic::NonFiniteSamples {
220 count: counts.non_finite,
221 });
222 }
223 if counts.out_of_range > 0 {
224 diagnostics.push(Diagnostic::OutOfHalfRange {
225 count: counts.out_of_range,
226 });
227 }
228 Ok(ExrImage {
229 width,
230 height,
231 pixels,
232 color,
233 diagnostics,
234 })
235}
236
237fn check_channel_lists(bytes: &[u8]) -> Result<(), ExtensionError> {
243 fn text(bytes: &[u8], at: &mut usize) -> Option<Vec<u8>> {
245 let rest = bytes.get(*at..)?;
246 let end = 1 + rest
247 .get(1..)?
248 .iter()
249 .take(256)
250 .position(|byte| *byte == 0)?;
251 *at += end + 1;
252 Some(rest[..end].to_vec())
253 }
254 let Some(flags) = bytes.get(4..8) else {
255 return Ok(());
256 };
257 let multipart = flags[1] & 0x10 != 0;
258 let mut at = 8;
259 loop {
260 let mut attributes = 0;
261 loop {
262 match bytes.get(at) {
263 None => return Ok(()),
264 Some(0) => {
265 at += 1;
266 break;
267 }
268 Some(_) => {}
269 }
270 let Some(name) = text(bytes, &mut at) else {
271 return Ok(());
272 };
273 attributes += 1;
274 let Some(kind) = text(bytes, &mut at) else {
275 return Ok(());
276 };
277 let Some(size) = bytes
278 .get(at..at + 4)
279 .and_then(|size| usize::try_from(i32::from_le_bytes(size.try_into().ok()?)).ok())
280 else {
281 return Ok(());
282 };
283 if kind == b"chlist" && name != b"channels" {
284 return Err(ExtensionError::Malformed(format!(
285 "a header holds a channel list besides `channels`: `{}`",
286 String::from_utf8_lossy(&name)
287 )));
288 }
289 at = at.saturating_add(4).saturating_add(size);
290 }
291 if !multipart || attributes == 0 {
293 return Ok(());
294 }
295 }
296}
297
298fn check_channel(channel: &ChannelDescription) -> Result<(), ExtensionError> {
300 if channel.sampling.x() != 1 || channel.sampling.y() != 1 {
301 return Err(ExtensionError::Unsupported(format!(
302 "channel {} is subsampled",
303 channel.name
304 )));
305 }
306 if channel.sample_type == SampleType::U32 {
307 return Err(ExtensionError::Unsupported(format!(
308 "channel {} holds integers, not colors",
309 channel.name
310 )));
311 }
312 Ok(())
313}
314
315fn check_part(
317 header: &exr::meta::header::Header,
318 width: u32,
319 height: u32,
320 part: usize,
321 parts: usize,
322) -> Result<Vec<Diagnostic>, ExtensionError> {
323 check_canvas(width, height)?;
324 let data_pixels = u64::try_from(header.layer_size.x())
325 .unwrap_or(u64::MAX)
326 .saturating_mul(u64::try_from(header.layer_size.y()).unwrap_or(u64::MAX));
327 if data_pixels > MAX_CANVAS_PIXELS {
328 return Err(ExtensionError::Budget(format!(
329 "a {}x{} data window is larger than {MAX_CANVAS_PIXELS} pixels",
330 header.layer_size.x(),
331 header.layer_size.y()
332 )));
333 }
334 let mut diagnostics = Vec::new();
335 if parts > 1 {
336 diagnostics.push(Diagnostic::UnsupportedFeature {
337 feature: "more than one part".into(),
338 path: format!("/parts/{}", usize::from(part == 0)),
339 count: parts - 1,
340 });
341 }
342 let aspect = header.shared_attributes.pixel_aspect;
343 if (aspect - 1.0).abs() > 1e-6 {
344 diagnostics.push(Diagnostic::UnsupportedFeature {
345 feature: format!("pixel aspect ratio {aspect}"),
346 path: "/pixelAspectRatio".into(),
347 count: 1,
348 });
349 }
350 Ok(diagnostics)
351}
352
353fn place(offset: i64, at: usize, size: usize) -> Option<usize> {
355 usize::try_from(offset + i64::try_from(at).ok()?)
356 .ok()
357 .filter(|position| *position < size)
358}
359
360struct Canvas {
362 width: usize,
363 height: usize,
364 offset: (i64, i64),
366 shown: [Option<usize>; 4],
368 matrix: Option<[[f32; 3]; 3]>,
369 row: Vec<Vec<f32>>,
371 pixels: Vec<u16>,
372 counts: Counts,
373}
374
375impl Canvas {
376 fn new(
377 header: &exr::meta::header::Header,
378 display: exr::meta::attribute::IntegerBounds,
379 (width, height): (u32, u32),
380 shown: [Option<usize>; 4],
381 matrix: Option<[[f32; 3]; 3]>,
382 ) -> Self {
383 let position = header.own_attributes.layer_position;
384 let mut canvas = Self {
385 width: width as usize,
386 height: height as usize,
387 offset: (
388 i64::from(position.x()) - i64::from(display.position.x()),
389 i64::from(position.y()) - i64::from(display.position.y()),
390 ),
391 shown,
392 matrix,
393 row: vec![Vec::new(); header.channels.list.len()],
394 pixels: vec![0; width as usize * height as usize * 4],
395 counts: Counts::default(),
396 };
397 let blank = canvas.pixel(|_| Some(0.0));
399 let size = header.layer_size;
400 for data_y in 0..size.y() {
401 let Some(y) = place(canvas.offset.1, data_y, canvas.height) else {
402 continue;
403 };
404 for data_x in 0..size.x() {
405 if let Some(x) = place(canvas.offset.0, data_x, canvas.width) {
406 canvas.pixels[(y * canvas.width + x) * 4..][..4].copy_from_slice(&blank);
407 }
408 }
409 }
410 canvas
411 }
412
413 fn pixel(&mut self, mut sample: impl FnMut(usize) -> Option<f32>) -> [u16; 4] {
415 let shown = self.shown;
416 let counts = &mut self.counts;
417 let mut value = |slot: usize, missing: f32| {
418 shown[slot].and_then(&mut sample).map_or(missing, |value| {
419 if value.is_finite() {
420 value
421 } else {
422 counts.non_finite += 1;
423 0.0
424 }
425 })
426 };
427 let alpha = value(3, 1.0).clamp(0.0, 1.0);
428 let mut rgb = [value(0, 0.0), value(1, 0.0), value(2, 0.0)];
429 if let Some(matrix) = &self.matrix {
430 rgb = multiply(matrix, rgb);
431 }
432 [rgb[0], rgb[1], rgb[2], alpha].map(|value| to_half(value, counts))
433 }
434
435 fn place_block(&mut self, block: &exr::block::UncompressedBlock, channels: &ChannelList) {
437 let last = channels.list.len() - 1;
438 for line in block.lines(channels) {
439 let channel = line.location.channel;
440 if self.shown.contains(&Some(channel)) {
441 let row = &mut self.row[channel];
442 row.clear();
443 match channels.list[channel].sample_type {
444 SampleType::F16 => row.extend(
445 line.read_samples::<f16>()
446 .map(|sample| sample.map_or(f32::NAN, f16::to_f32)),
447 ),
448 _ => row.extend(
449 line.read_samples::<f32>()
450 .map(|sample| sample.unwrap_or(f32::NAN)),
451 ),
452 }
453 }
454 if channel != last {
455 continue;
456 }
457 let Some(y) = place(self.offset.1, line.location.position.y(), self.height) else {
458 continue;
459 };
460 for at in 0..line.location.sample_count {
461 let data_x = line.location.position.x() + at;
462 let Some(x) = place(self.offset.0, data_x, self.width) else {
463 continue;
464 };
465 let row = std::mem::take(&mut self.row);
466 let pixel = self.pixel(|channel| row[channel].get(at).copied());
467 self.row = row;
468 self.pixels[(y * self.width + x) * 4..][..4].copy_from_slice(&pixel);
469 }
470 }
471 }
472}
473
474#[derive(Default)]
476struct Counts {
477 non_finite: usize,
478 out_of_range: usize,
479}
480
481fn to_half(value: f32, counts: &mut Counts) -> u16 {
484 if value.is_nan() {
485 counts.non_finite += 1;
486 return 0;
487 }
488 let half = f16::from_f32(value);
489 if half.is_infinite() {
490 counts.out_of_range += 1;
491 return if value > 0.0 { f16::MAX } else { f16::MIN }.to_bits();
492 }
493 half.to_bits()
494}
495
496fn channels_shown(names: impl Iterator<Item = String>) -> Option<[Option<usize>; 4]> {
498 let names = names.collect::<Vec<_>>();
499 let find = |name: &str| names.iter().position(|candidate| candidate == name);
500 let alpha = find("A");
501 match (find("R"), find("G"), find("B"), find("Y")) {
502 (Some(red), Some(green), Some(blue), _) => {
503 Some([Some(red), Some(green), Some(blue), alpha])
504 }
505 (_, _, _, Some(luma)) => Some([Some(luma), Some(luma), Some(luma), alpha]),
506 _ => None,
507 }
508}
509
510fn exr_error(error: exr::error::Error) -> ExtensionError {
511 match error {
512 exr::error::Error::NotSupported(message) => ExtensionError::Unsupported(message.into()),
513 other => ExtensionError::Malformed(other.to_string()),
514 }
515}
516
517fn file_color(declared: Option<exr::meta::attribute::Chromaticities>) -> LinearColor {
519 let Some(declared) = declared else {
520 return LinearColor {
521 primaries: Some(LinearPrimaries::Bt709),
522 chromaticities: named_chromaticities(LinearPrimaries::Bt709),
523 origin: ColorOrigin::FormatDefault,
524 };
525 };
526 let chromaticities = [declared.red, declared.green, declared.blue, declared.white]
527 .map(|point| [point.x(), point.y()]);
528 LinearColor {
529 primaries: PRIMARIES.into_iter().find(|named| {
530 named_chromaticities(*named)
531 .iter()
532 .flatten()
533 .zip(chromaticities.iter().flatten())
534 .all(|(a, b)| (a - b).abs() < 5e-4)
535 }),
536 chromaticities,
537 origin: ColorOrigin::File,
538 }
539}
540
541const PRIMARIES: [LinearPrimaries; 5] = [
542 LinearPrimaries::Bt709,
543 LinearPrimaries::Bt2020,
544 LinearPrimaries::P3D65,
545 LinearPrimaries::AcesAp0,
546 LinearPrimaries::AcesAp1,
547];
548
549const D65: [f32; 2] = [0.3127, 0.3290];
550const ACES_WHITE: [f32; 2] = [0.32168, 0.33767];
551
552pub(crate) const fn named_chromaticities(primaries: LinearPrimaries) -> [[f32; 2]; 4] {
554 match primaries {
555 LinearPrimaries::Bt709 => [[0.64, 0.33], [0.30, 0.60], [0.15, 0.06], D65],
556 LinearPrimaries::Bt2020 => [[0.708, 0.292], [0.170, 0.797], [0.131, 0.046], D65],
557 LinearPrimaries::P3D65 => [[0.680, 0.320], [0.265, 0.690], [0.150, 0.060], D65],
558 LinearPrimaries::AcesAp0 => [[0.7347, 0.2653], [0.0, 1.0], [0.0001, -0.0770], ACES_WHITE],
559 LinearPrimaries::AcesAp1 => [[0.713, 0.293], [0.165, 0.830], [0.128, 0.044], ACES_WHITE],
560 }
561}
562
563type Matrix = [[f64; 3]; 3];
564
565fn to_bt709(chromaticities: [[f32; 2]; 4]) -> Option<[[f32; 3]; 3]> {
567 let bt709 = named_chromaticities(LinearPrimaries::Bt709);
568 if chromaticities == bt709 {
569 return None;
570 }
571 let to_xyz = rgb_to_xyz(chromaticities);
572 let adapt = bradford(chromaticities[3], D65);
573 let from_xyz = invert(&rgb_to_xyz(bt709));
574 let matrix = product(&from_xyz, &product(&adapt, &to_xyz));
575 #[allow(clippy::cast_possible_truncation)]
577 Some(matrix.map(|row| row.map(|value| value as f32)))
578}
579
580fn defines_color_space(chromaticities: [[f32; 2]; 4]) -> bool {
582 to_bt709(chromaticities)
583 .is_none_or(|matrix| matrix.iter().flatten().all(|value| value.is_finite()))
584}
585
586fn multiply(matrix: &[[f32; 3]; 3], rgb: [f32; 3]) -> [f32; 3] {
587 matrix.map(|row| row[0] * rgb[0] + row[1] * rgb[1] + row[2] * rgb[2])
588}
589
590fn xyz_of(point: [f32; 2]) -> [f64; 3] {
591 let (x, y) = (f64::from(point[0]), f64::from(point[1]));
592 [x / y, 1.0, (1.0 - x - y) / y]
593}
594
595fn rgb_to_xyz(chromaticities: [[f32; 2]; 4]) -> Matrix {
597 let columns = [0, 1, 2].map(|index| xyz_of(chromaticities[index]));
598 let primaries = [0, 1, 2].map(|row| columns.map(|column| column[row]));
599 let white = xyz_of(chromaticities[3]);
600 let scale = apply(&invert(&primaries), white);
601 primaries.map(|row| [row[0] * scale[0], row[1] * scale[1], row[2] * scale[2]])
602}
603
604fn bradford(from: [f32; 2], to: [f32; 2]) -> Matrix {
606 const CONE: Matrix = [
607 [0.8951, 0.2664, -0.1614],
608 [-0.7502, 1.7135, 0.0367],
609 [0.0389, -0.0685, 1.0296],
610 ];
611 let source = apply(&CONE, xyz_of(from));
612 let target = apply(&CONE, xyz_of(to));
613 let scale = [0, 1, 2].map(|index| {
614 let mut row = [0.0; 3];
615 row[index] = target[index] / source[index];
616 row
617 });
618 product(&invert(&CONE), &product(&scale, &CONE))
619}
620
621fn apply(matrix: &Matrix, vector: [f64; 3]) -> [f64; 3] {
622 matrix.map(|row| row[0] * vector[0] + row[1] * vector[1] + row[2] * vector[2])
623}
624
625fn product(a: &Matrix, b: &Matrix) -> Matrix {
626 let mut out = [[0.0; 3]; 3];
627 for (row, out_row) in out.iter_mut().enumerate() {
628 for (column, value) in out_row.iter_mut().enumerate() {
629 *value = (0..3).map(|k| a[row][k] * b[k][column]).sum();
630 }
631 }
632 out
633}
634
635fn invert(m: &Matrix) -> Matrix {
636 let cofactor =
637 |r0: usize, r1: usize, c0: usize, c1: usize| m[r0][c0] * m[r1][c1] - m[r0][c1] * m[r1][c0];
638 let adjugate = [
639 [
640 cofactor(1, 2, 1, 2),
641 -cofactor(0, 2, 1, 2),
642 cofactor(0, 1, 1, 2),
643 ],
644 [
645 -cofactor(1, 2, 0, 2),
646 cofactor(0, 2, 0, 2),
647 -cofactor(0, 1, 0, 2),
648 ],
649 [
650 cofactor(1, 2, 0, 1),
651 -cofactor(0, 2, 0, 1),
652 cofactor(0, 1, 0, 1),
653 ],
654 ];
655 let determinant =
656 m[0][0] * adjugate[0][0] + m[0][1] * adjugate[1][0] + m[0][2] * adjugate[2][0];
657 adjugate.map(|row| row.map(|value| value / determinant))
658}
659
660#[cfg(test)]
661pub(crate) fn matrix_to_bt709(primaries: LinearPrimaries) -> Option<[[f32; 3]; 3]> {
662 to_bt709(named_chromaticities(primaries))
663}