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