Skip to main content

astrs_node_api/message/
media.rs

1//! `std/media/v1` — images and audio (§24.3).
2//!
3//! | Type | URN | Layout |
4//! |---|---|---|
5//! | [`Image`] | `Image[pixel=…]` | `{width, height, stride: UInt32, channels: UInt8, data: List<sample>}` |
6//! | [`AudioFrame`] | `AudioFrame[sample=…]` | `{sample_rate: UInt32, channels: UInt16, data: List<sample>}` |
7//! | [`CompressedImage`] | `CompressedImage[format=…]` | `{format: Utf8, data: Binary}` |
8//!
9//! [`Image`] and [`AudioFrame`] have a layout that *depends* on their URN
10//! parameter — the sample column is `UInt8` for `rgb8` and `Float32` for
11//! `rgb32f` — which a `const URN: &'static str` cannot express. Both carry
12//! the parameter as a Rust value ([`PixelFormat`], [`SampleFormat`]) and
13//! expose inherent `to_record_batch`/`from_record_batch` plus a `urn()` that
14//! renders what a port should declare. [`CompressedImage`]'s layout does not
15//! vary with its `format` (an encoded stream is opaque bytes whatever the
16//! codec), so it implements [`AstrsMessage`] proper.
17//!
18//! Decoding an [`Image`] payload into `astrs-data`'s
19//! [`astrs_data::tensor::ImageView`] — the shape blueprint §9.1
20//! shows (`let img: ImageView = data.view()?;`) — works through this module's
21//! [`super::FromPayload`] implementation for that type, which is
22//! read-only because an `ImageView` is a checked view over columns somebody
23//! else built.
24//!
25//! # Examples
26//!
27//! ```
28//! use astrs_node_api::message::{Image, ImageSamples, PixelFormat};
29//!
30//! let frame = Image::new(PixelFormat::Mono8, 2, 2, ImageSamples::U8(vec![1, 2, 3, 4]))?;
31//! assert_eq!(frame.urn(), "std/media/v1/Image[pixel=mono8]");
32//! let batch = frame.to_record_batch()?;
33//! assert_eq!(Image::from_record_batch(&batch)?, frame);
34//! # Ok::<(), astrs_data::DataError>(())
35//! ```
36
37use astrs_data::tensor::ImageView;
38use astrs_data::{AstrsMessage, DataError, DataType, Field, RecordBatch, Result};
39
40use super::{FromPayload, build, read, single_row_column};
41
42/// A pixel format from the §24.3 `Image[pixel=…]` table.
43#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
44#[non_exhaustive]
45pub enum PixelFormat {
46    /// Single-channel 8-bit grey.
47    Mono8,
48    /// Single-channel 16-bit grey.
49    Mono16,
50    /// Single-channel 32-bit float grey.
51    Mono32F,
52    /// Three-channel 8-bit RGB.
53    Rgb8,
54    /// Three-channel 8-bit BGR.
55    Bgr8,
56    /// Four-channel 8-bit RGBA.
57    Rgba8,
58    /// Four-channel 8-bit BGRA.
59    Bgra8,
60    /// Three-channel 16-bit RGB.
61    Rgb16,
62    /// Four-channel 16-bit RGBA.
63    Rgba16,
64    /// Three-channel 32-bit float RGB.
65    Rgb32F,
66    /// Four-channel 32-bit float RGBA.
67    Rgba32F,
68}
69
70impl PixelFormat {
71    /// Every format, in documentation order.
72    pub const ALL: &'static [Self] = &[
73        Self::Mono8,
74        Self::Mono16,
75        Self::Mono32F,
76        Self::Rgb8,
77        Self::Bgr8,
78        Self::Rgba8,
79        Self::Bgra8,
80        Self::Rgb16,
81        Self::Rgba16,
82        Self::Rgb32F,
83        Self::Rgba32F,
84    ];
85
86    /// The `pixel=` parameter value.
87    #[must_use]
88    pub const fn as_str(self) -> &'static str {
89        match self {
90            Self::Mono8 => "mono8",
91            Self::Mono16 => "mono16",
92            Self::Mono32F => "mono32f",
93            Self::Rgb8 => "rgb8",
94            Self::Bgr8 => "bgr8",
95            Self::Rgba8 => "rgba8",
96            Self::Bgra8 => "bgra8",
97            Self::Rgb16 => "rgb16",
98            Self::Rgba16 => "rgba16",
99            Self::Rgb32F => "rgb32f",
100            Self::Rgba32F => "rgba32f",
101        }
102    }
103
104    /// The format a `pixel=` value names.
105    #[must_use]
106    pub fn parse(value: &str) -> Option<Self> {
107        Self::ALL
108            .iter()
109            .copied()
110            .find(|format| format.as_str() == value)
111    }
112
113    /// How many channels one pixel holds.
114    #[must_use]
115    pub const fn channels(self) -> u8 {
116        match self {
117            Self::Mono8 | Self::Mono16 | Self::Mono32F => 1,
118            Self::Rgb8 | Self::Bgr8 | Self::Rgb16 | Self::Rgb32F => 3,
119            Self::Rgba8 | Self::Bgra8 | Self::Rgba16 | Self::Rgba32F => 4,
120        }
121    }
122
123    /// The columnar type one sample occupies.
124    #[must_use]
125    pub const fn sample_type(self) -> DataType {
126        match self {
127            Self::Mono8 | Self::Rgb8 | Self::Bgr8 | Self::Rgba8 | Self::Bgra8 => DataType::UInt8,
128            Self::Mono16 | Self::Rgb16 | Self::Rgba16 => DataType::UInt16,
129            Self::Mono32F | Self::Rgb32F | Self::Rgba32F => DataType::Float32,
130        }
131    }
132
133    /// The parameterised URN a port carrying this format declares.
134    #[must_use]
135    pub fn urn(self) -> String {
136        format!("std/media/v1/Image[pixel={}]", self.as_str())
137    }
138
139    /// The columnar layout an image in this format produces.
140    #[must_use]
141    pub fn layout(self) -> DataType {
142        DataType::strukt([
143            Field::required("width", DataType::UInt32),
144            Field::required("height", DataType::UInt32),
145            Field::required("stride", DataType::UInt32),
146            Field::required("channels", DataType::UInt8),
147            Field::required(
148                "data",
149                DataType::list(Field::required("sample", self.sample_type())),
150            ),
151        ])
152    }
153}
154
155impl core::fmt::Display for PixelFormat {
156    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
157        f.write_str(self.as_str())
158    }
159}
160
161/// An image's samples, in whichever width its [`PixelFormat`] selects.
162#[derive(Debug, Clone, PartialEq)]
163#[non_exhaustive]
164pub enum ImageSamples {
165    /// 8-bit samples.
166    U8(Vec<u8>),
167    /// 16-bit samples.
168    U16(Vec<u16>),
169    /// 32-bit float samples.
170    F32(Vec<f32>),
171}
172
173impl ImageSamples {
174    /// How many samples the buffer holds.
175    #[must_use]
176    pub fn len(&self) -> usize {
177        match self {
178            Self::U8(values) => values.len(),
179            Self::U16(values) => values.len(),
180            Self::F32(values) => values.len(),
181        }
182    }
183
184    /// Whether the buffer is empty.
185    #[must_use]
186    pub fn is_empty(&self) -> bool {
187        self.len() == 0
188    }
189
190    /// The columnar type these samples occupy.
191    #[must_use]
192    pub const fn sample_type(&self) -> DataType {
193        match self {
194            Self::U8(_) => DataType::UInt8,
195            Self::U16(_) => DataType::UInt16,
196            Self::F32(_) => DataType::Float32,
197        }
198    }
199}
200
201/// A raw image frame — `std/media/v1/Image[pixel=…]`, row-major and packed.
202#[derive(Debug, Clone, PartialEq)]
203pub struct Image {
204    /// The pixel format, which selects the sample column's type.
205    pub pixel: PixelFormat,
206    /// The frame's width in pixels.
207    pub width: u32,
208    /// The frame's height in pixels.
209    pub height: u32,
210    /// The bytes between the starts of two rows; equal to the packed row
211    /// length for a frame with no padding, which is what this layout carries.
212    pub stride: u32,
213    /// The samples, `width * height * channels` of them.
214    pub data: ImageSamples,
215}
216
217impl Image {
218    /// A packed frame whose sample count matches its geometry.
219    ///
220    /// `stride` is computed as the packed row length in *bytes*.
221    ///
222    /// # Errors
223    ///
224    /// [`DataError::TypeMismatch`] when the samples do not match the format's
225    /// width, and [`DataError::ChildLengthMismatch`] when the sample count is
226    /// not `width * height * channels`.
227    pub fn new(pixel: PixelFormat, width: u32, height: u32, data: ImageSamples) -> Result<Self> {
228        let stride = packed_stride(pixel, width);
229        let value = Self {
230            pixel,
231            width,
232            height,
233            stride,
234            data,
235        };
236        value.check()?;
237        Ok(value)
238    }
239
240    /// How many channels one pixel holds.
241    #[must_use]
242    pub const fn channels(&self) -> u8 {
243        self.pixel.channels()
244    }
245
246    /// The parameterised URN a port carrying this frame declares.
247    #[must_use]
248    pub fn urn(&self) -> String {
249        self.pixel.urn()
250    }
251
252    /// The columnar layout this frame produces.
253    #[must_use]
254    pub fn layout(&self) -> DataType {
255        self.pixel.layout()
256    }
257
258    /// Checks that the samples match the format and the geometry.
259    ///
260    /// # Errors
261    ///
262    /// As [`Image::new`].
263    pub fn check(&self) -> Result<()> {
264        if self.data.sample_type() != self.pixel.sample_type() {
265            return Err(DataError::type_mismatch(
266                self.pixel.sample_type(),
267                self.data.sample_type(),
268            ));
269        }
270        let expected = expected_samples(self.width, self.height, self.channels());
271        if self.data.len() != expected {
272            return Err(DataError::ChildLengthMismatch {
273                expected,
274                actual: self.data.len(),
275            });
276        }
277        Ok(())
278    }
279
280    /// Encodes the frame as a one-row payload batch.
281    ///
282    /// # Errors
283    ///
284    /// As [`Image::check`], plus [`DataError`] when the columns cannot be
285    /// assembled.
286    pub fn to_record_batch(&self) -> Result<RecordBatch> {
287        self.check()?;
288        let samples = match &self.data {
289            ImageSamples::U8(values) => build::primitive_lists::<u8>("sample", &[values])?,
290            ImageSamples::U16(values) => build::primitive_lists::<u16>("sample", &[values])?,
291            ImageSamples::F32(values) => build::primitive_lists::<f32>("sample", &[values])?,
292        };
293        let column = build::structure(vec![
294            ("width", build::primitive::<u32>(&[self.width])),
295            ("height", build::primitive::<u32>(&[self.height])),
296            ("stride", build::primitive::<u32>(&[self.stride])),
297            ("channels", build::primitive::<u8>(&[self.pixel.channels()])),
298            ("data", samples),
299        ])?;
300        Ok(RecordBatch::from_payload(column))
301    }
302
303    /// Decodes a frame from a one-row payload batch.
304    ///
305    /// The pixel format is recovered from the sample column's type and the
306    /// stored channel count, so a decoder never needs the port's URN to read
307    /// a frame it already holds.
308    ///
309    /// # Errors
310    ///
311    /// [`DataError`] when the batch is not an `Image` layout, or its sample
312    /// type and channel count name no format in the §24.3 table.
313    pub fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
314        let column = single_row_column(batch)?;
315        let width = read::primitive_at::<u32>(read::child(column, "width")?, 0)?;
316        let height = read::primitive_at::<u32>(read::child(column, "height")?, 0)?;
317        let stride = read::primitive_at::<u32>(read::child(column, "stride")?, 0)?;
318        let channels = read::primitive_at::<u8>(read::child(column, "channels")?, 0)?;
319        let data_column = read::child(column, "data")?;
320        let sample_type = match data_column.data_type() {
321            DataType::List(field) => field.data_type().clone(),
322            other => {
323                return Err(DataError::type_mismatch(
324                    DataType::list(Field::required("sample", DataType::UInt8)),
325                    other.clone(),
326                ));
327            }
328        };
329        let data = match sample_type {
330            DataType::UInt8 => ImageSamples::U8(read::primitive_list_at::<u8>(data_column, 0)?),
331            DataType::UInt16 => ImageSamples::U16(read::primitive_list_at::<u16>(data_column, 0)?),
332            DataType::Float32 => ImageSamples::F32(read::primitive_list_at::<f32>(data_column, 0)?),
333            other => return Err(DataError::type_mismatch(DataType::UInt8, other)),
334        };
335        let pixel = pixel_for(&data.sample_type(), channels)
336            .ok_or_else(|| DataError::type_mismatch(DataType::UInt8, data.sample_type()))?;
337        let value = Self {
338            pixel,
339            width,
340            height,
341            stride,
342            data,
343        };
344        value.check()?;
345        Ok(value)
346    }
347}
348
349impl FromPayload for Image {
350    fn from_batch(batch: &RecordBatch) -> Result<Self> {
351        Self::from_record_batch(batch)
352    }
353}
354
355impl FromPayload for ImageView {
356    /// Reads an `std/media/v1/Image` payload as a checked N-D view.
357    ///
358    /// This is the blueprint §9.1 shape: `let img: ImageView = data.view()?;`
359    /// — a *view*, not a copy, over the payload's own sample column.
360    fn from_batch(batch: &RecordBatch) -> Result<Self> {
361        let column = single_row_column(batch)?;
362        let strukt = read::structure(column)?;
363        Self::from_struct_row(strukt, 0)
364    }
365}
366
367/// An audio sample format from the §24.3 `AudioFrame[sample=…]` table.
368#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
369#[non_exhaustive]
370pub enum SampleFormat {
371    /// Unsigned 8-bit PCM.
372    U8,
373    /// Signed 8-bit PCM.
374    S8,
375    /// Signed 16-bit PCM.
376    S16,
377    /// Signed 32-bit PCM.
378    S32,
379    /// 32-bit float PCM.
380    F32,
381    /// 64-bit float PCM.
382    F64,
383}
384
385impl SampleFormat {
386    /// Every format, in documentation order.
387    pub const ALL: &'static [Self] = &[
388        Self::U8,
389        Self::S8,
390        Self::S16,
391        Self::S32,
392        Self::F32,
393        Self::F64,
394    ];
395
396    /// The `sample=` parameter value.
397    #[must_use]
398    pub const fn as_str(self) -> &'static str {
399        match self {
400            Self::U8 => "u8",
401            Self::S8 => "s8",
402            Self::S16 => "s16",
403            Self::S32 => "s32",
404            Self::F32 => "f32",
405            Self::F64 => "f64",
406        }
407    }
408
409    /// The format a `sample=` value names.
410    #[must_use]
411    pub fn parse(value: &str) -> Option<Self> {
412        Self::ALL
413            .iter()
414            .copied()
415            .find(|format| format.as_str() == value)
416    }
417
418    /// The columnar type one sample occupies.
419    #[must_use]
420    pub const fn sample_type(self) -> DataType {
421        match self {
422            Self::U8 => DataType::UInt8,
423            Self::S8 => DataType::Int8,
424            Self::S16 => DataType::Int16,
425            Self::S32 => DataType::Int32,
426            Self::F32 => DataType::Float32,
427            Self::F64 => DataType::Float64,
428        }
429    }
430
431    /// The parameterised URN a port carrying this format declares.
432    #[must_use]
433    pub fn urn(self) -> String {
434        format!("std/media/v1/AudioFrame[sample={}]", self.as_str())
435    }
436
437    /// The columnar layout an audio frame in this format produces.
438    #[must_use]
439    pub fn layout(self) -> DataType {
440        DataType::strukt([
441            Field::required("sample_rate", DataType::UInt32),
442            Field::required("channels", DataType::UInt16),
443            Field::required(
444                "data",
445                DataType::list(Field::required("sample", self.sample_type())),
446            ),
447        ])
448    }
449}
450
451impl core::fmt::Display for SampleFormat {
452    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
453        f.write_str(self.as_str())
454    }
455}
456
457/// A block of interleaved PCM audio — `std/media/v1/AudioFrame[sample=…]`.
458///
459/// Samples are interleaved across channels (`frame 0 ch 0, frame 0 ch 1, …`),
460/// which is the layout a capture ring buffer already holds.
461#[derive(Debug, Clone, PartialEq)]
462pub struct AudioFrame {
463    /// The sample format, which selects the sample column's type.
464    pub format: SampleFormat,
465    /// Frames per second.
466    pub sample_rate: u32,
467    /// How many channels are interleaved.
468    pub channels: u16,
469    /// The interleaved samples, as 32-bit floats regardless of the wire
470    /// format — the one shape every audio pipeline can consume, converted on
471    /// encode.
472    pub data: Vec<f32>,
473}
474
475impl AudioFrame {
476    /// A frame of interleaved `f32` samples.
477    ///
478    /// # Errors
479    ///
480    /// [`DataError::ChildLengthMismatch`] when the sample count is not a
481    /// whole number of interleaved frames.
482    pub fn new(
483        format: SampleFormat,
484        sample_rate: u32,
485        channels: u16,
486        data: Vec<f32>,
487    ) -> Result<Self> {
488        let value = Self {
489            format,
490            sample_rate,
491            channels,
492            data,
493        };
494        value.check()?;
495        Ok(value)
496    }
497
498    /// How many interleaved frames the block holds.
499    #[must_use]
500    pub fn frame_count(&self) -> usize {
501        let channels = usize::from(self.channels.max(1));
502        self.data.len() / channels
503    }
504
505    /// The parameterised URN a port carrying this frame declares.
506    #[must_use]
507    pub fn urn(&self) -> String {
508        self.format.urn()
509    }
510
511    /// The columnar layout this frame produces.
512    #[must_use]
513    pub fn layout(&self) -> DataType {
514        self.format.layout()
515    }
516
517    /// Checks that the sample count is a whole number of frames.
518    ///
519    /// # Errors
520    ///
521    /// [`DataError::ChildLengthMismatch`].
522    pub fn check(&self) -> Result<()> {
523        let channels = usize::from(self.channels.max(1));
524        if self.data.len().is_multiple_of(channels) {
525            Ok(())
526        } else {
527            Err(DataError::ChildLengthMismatch {
528                expected: self.data.len().next_multiple_of(channels),
529                actual: self.data.len(),
530            })
531        }
532    }
533
534    /// Encodes the frame as a one-row payload batch, converting the samples
535    /// into the format's own column type.
536    ///
537    /// # Errors
538    ///
539    /// As [`AudioFrame::check`], plus [`DataError`] when the columns cannot be
540    /// assembled.
541    pub fn to_record_batch(&self) -> Result<RecordBatch> {
542        self.check()?;
543        let samples = match self.format {
544            SampleFormat::U8 => build::primitive_lists::<u8>(
545                "sample",
546                &[&self.data.iter().map(|v| clamp_u8(*v)).collect::<Vec<u8>>()],
547            )?,
548            SampleFormat::S8 => build::primitive_lists::<i8>(
549                "sample",
550                &[&self.data.iter().map(|v| clamp_i8(*v)).collect::<Vec<i8>>()],
551            )?,
552            SampleFormat::S16 => build::primitive_lists::<i16>(
553                "sample",
554                &[&self
555                    .data
556                    .iter()
557                    .map(|v| clamp_i16(*v))
558                    .collect::<Vec<i16>>()],
559            )?,
560            SampleFormat::S32 => build::primitive_lists::<i32>(
561                "sample",
562                &[&self
563                    .data
564                    .iter()
565                    .map(|v| clamp_i32(*v))
566                    .collect::<Vec<i32>>()],
567            )?,
568            SampleFormat::F32 => build::primitive_lists::<f32>("sample", &[&self.data])?,
569            SampleFormat::F64 => build::primitive_lists::<f64>(
570                "sample",
571                &[&self
572                    .data
573                    .iter()
574                    .map(|v| f64::from(*v))
575                    .collect::<Vec<f64>>()],
576            )?,
577        };
578        let column = build::structure(vec![
579            ("sample_rate", build::primitive::<u32>(&[self.sample_rate])),
580            ("channels", build::primitive::<u16>(&[self.channels])),
581            ("data", samples),
582        ])?;
583        Ok(RecordBatch::from_payload(column))
584    }
585
586    /// Decodes a frame from a one-row payload batch, converting the samples
587    /// back into `f32`.
588    ///
589    /// # Errors
590    ///
591    /// [`DataError`] when the batch is not an `AudioFrame` layout.
592    pub fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
593        let column = single_row_column(batch)?;
594        let sample_rate = read::primitive_at::<u32>(read::child(column, "sample_rate")?, 0)?;
595        let channels = read::primitive_at::<u16>(read::child(column, "channels")?, 0)?;
596        let data_column = read::child(column, "data")?;
597        let sample_type = match data_column.data_type() {
598            DataType::List(field) => field.data_type().clone(),
599            other => {
600                return Err(DataError::type_mismatch(
601                    DataType::list(Field::required("sample", DataType::Float32)),
602                    other.clone(),
603                ));
604            }
605        };
606        let (format, data) = match sample_type {
607            DataType::UInt8 => (
608                SampleFormat::U8,
609                read::primitive_list_at::<u8>(data_column, 0)?
610                    .into_iter()
611                    .map(narrow_u8)
612                    .collect(),
613            ),
614            DataType::Int8 => (
615                SampleFormat::S8,
616                read::primitive_list_at::<i8>(data_column, 0)?
617                    .into_iter()
618                    .map(narrow_i8)
619                    .collect(),
620            ),
621            DataType::Int16 => (
622                SampleFormat::S16,
623                read::primitive_list_at::<i16>(data_column, 0)?
624                    .into_iter()
625                    .map(narrow_i16)
626                    .collect(),
627            ),
628            DataType::Int32 => (
629                SampleFormat::S32,
630                read::primitive_list_at::<i32>(data_column, 0)?
631                    .into_iter()
632                    .map(narrow_i32)
633                    .collect(),
634            ),
635            DataType::Float32 => (
636                SampleFormat::F32,
637                read::primitive_list_at::<f32>(data_column, 0)?,
638            ),
639            DataType::Float64 => (
640                SampleFormat::F64,
641                read::primitive_list_at::<f64>(data_column, 0)?
642                    .into_iter()
643                    .map(narrow_f64)
644                    .collect(),
645            ),
646            other => return Err(DataError::type_mismatch(DataType::Float32, other)),
647        };
648        Self::new(format, sample_rate, channels, data)
649    }
650}
651
652impl FromPayload for AudioFrame {
653    fn from_batch(batch: &RecordBatch) -> Result<Self> {
654        Self::from_record_batch(batch)
655    }
656}
657
658/// An encoded image frame — `std/media/v1/CompressedImage[format=…]`.
659///
660/// The only parameterised media type whose *layout* does not vary with its
661/// parameter: an encoded stream is opaque bytes whatever the codec, and the
662/// codec name rides as row data so a decoder never needs the port's URN.
663#[derive(Debug, Clone, Default, PartialEq, Eq)]
664pub struct CompressedImage {
665    /// The codec that produced `data` (`jpeg`, `png`, `h264`, …).
666    pub format: String,
667    /// The encoded bytes.
668    pub data: Vec<u8>,
669}
670
671impl CompressedImage {
672    /// A frame from its codec name and bytes.
673    #[must_use]
674    pub fn new(format: impl Into<String>, data: Vec<u8>) -> Self {
675        Self {
676            format: format.into(),
677            data,
678        }
679    }
680
681    /// The parameterised URN a port carrying this frame declares.
682    #[must_use]
683    pub fn urn(&self) -> String {
684        format!("std/media/v1/CompressedImage[format={}]", self.format)
685    }
686
687    /// The columnar layout of this type.
688    #[must_use]
689    pub fn layout() -> DataType {
690        DataType::strukt([
691            Field::required("format", DataType::Utf8),
692            Field::required("data", DataType::Binary),
693        ])
694    }
695}
696
697impl AstrsMessage for CompressedImage {
698    const URN: &'static str = "std/media/v1/CompressedImage";
699
700    fn data_type() -> DataType {
701        Self::layout()
702    }
703
704    fn to_record_batch(&self) -> Result<RecordBatch> {
705        let column = build::structure(vec![
706            ("format", build::strings(&[&self.format])),
707            ("data", build::binaries(&[&self.data])),
708        ])?;
709        Ok(RecordBatch::from_payload(column))
710    }
711
712    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
713        let column = single_row_column(batch)?;
714        Ok(Self {
715            format: read::str_at(read::child(column, "format")?, 0)?.to_owned(),
716            data: read::bytes_at(read::child(column, "data")?, 0)?.to_vec(),
717        })
718    }
719}
720
721super::impl_from_payload!(CompressedImage);
722
723/// The packed row length in bytes for a format and width.
724fn packed_stride(pixel: PixelFormat, width: u32) -> u32 {
725    let sample_width = match pixel.sample_type() {
726        DataType::UInt8 => 1u64,
727        DataType::UInt16 => 2,
728        _ => 4,
729    };
730    let bytes = u64::from(width) * u64::from(pixel.channels()) * sample_width;
731    u32::try_from(bytes).unwrap_or(u32::MAX)
732}
733
734/// The sample count a geometry implies, saturating rather than wrapping.
735fn expected_samples(width: u32, height: u32, channels: u8) -> usize {
736    let total = u64::from(width) * u64::from(height) * u64::from(channels);
737    usize::try_from(total).unwrap_or(usize::MAX)
738}
739
740/// The format a `(sample type, channel count)` pair names, if any.
741fn pixel_for(sample_type: &DataType, channels: u8) -> Option<PixelFormat> {
742    PixelFormat::ALL
743        .iter()
744        .copied()
745        .find(|format| &format.sample_type() == sample_type && format.channels() == channels)
746}
747
748/// Scales a normalised `f32` sample into unsigned 8-bit PCM.
749fn clamp_u8(value: f32) -> u8 {
750    let scaled = (value.clamp(-1.0, 1.0) * 127.0) + 128.0;
751    #[expect(
752        clippy::cast_possible_truncation,
753        clippy::cast_sign_loss,
754        reason = "the value is clamped into 1.0..=255.0 before the cast"
755    )]
756    {
757        scaled.round().clamp(0.0, 255.0) as u8
758    }
759}
760
761/// Scales a normalised `f32` sample into signed 8-bit PCM.
762fn clamp_i8(value: f32) -> i8 {
763    #[expect(
764        clippy::cast_possible_truncation,
765        reason = "the value is clamped into i8's range before the cast"
766    )]
767    {
768        (value.clamp(-1.0, 1.0) * 127.0)
769            .round()
770            .clamp(-128.0, 127.0) as i8
771    }
772}
773
774/// Scales a normalised `f32` sample into signed 16-bit PCM.
775fn clamp_i16(value: f32) -> i16 {
776    #[expect(
777        clippy::cast_possible_truncation,
778        reason = "the value is clamped into i16's range before the cast"
779    )]
780    {
781        (value.clamp(-1.0, 1.0) * 32_767.0)
782            .round()
783            .clamp(-32_768.0, 32_767.0) as i16
784    }
785}
786
787/// Scales a normalised `f32` sample into signed 32-bit PCM.
788fn clamp_i32(value: f32) -> i32 {
789    #[expect(
790        clippy::cast_possible_truncation,
791        reason = "the value is clamped into i32's range before the cast"
792    )]
793    {
794        (f64::from(value.clamp(-1.0, 1.0)) * 2_147_483_647.0)
795            .round()
796            .clamp(-2_147_483_648.0, 2_147_483_647.0) as i32
797    }
798}
799
800/// Scales unsigned 8-bit PCM back into a normalised `f32`, undoing
801/// [`clamp_u8`]'s mid-scale offset.
802fn narrow_u8(value: u8) -> f32 {
803    (f32::from(value) - 128.0) / 127.0
804}
805
806/// Scales signed 8-bit PCM back into a normalised `f32`.
807fn narrow_i8(value: i8) -> f32 {
808    f32::from(value) / 127.0
809}
810
811/// Scales signed 16-bit PCM back into a normalised `f32`.
812fn narrow_i16(value: i16) -> f32 {
813    f32::from(value) / 32_767.0
814}
815
816/// Scales signed 32-bit PCM back into a normalised `f32`.
817fn narrow_i32(value: i32) -> f32 {
818    #[expect(
819        clippy::cast_possible_truncation,
820        reason = "a normalised ratio is well inside f32's range"
821    )]
822    {
823        (f64::from(value) / 2_147_483_647.0) as f32
824    }
825}
826
827/// Narrows a `f64` sample to `f32`.
828fn narrow_f64(value: f64) -> f32 {
829    #[expect(
830        clippy::cast_possible_truncation,
831        reason = "PCM samples are normalised, so the narrowing is lossless in practice"
832    )]
833    {
834        value as f32
835    }
836}
837
838#[cfg(test)]
839mod tests {
840    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
841
842    use super::*;
843    use crate::message::{assert_layout_matches, assert_registry_layout_for};
844
845    #[test]
846    fn every_pixel_format_layout_matches_the_registry() {
847        for format in PixelFormat::ALL {
848            assert_layout_matches(&format.urn(), &format.layout()).unwrap();
849            assert_eq!(PixelFormat::parse(format.as_str()), Some(*format));
850            assert_eq!(format.to_string(), format.as_str());
851        }
852        assert_eq!(PixelFormat::parse("nope"), None);
853    }
854
855    #[test]
856    fn every_sample_format_layout_matches_the_registry() {
857        for format in SampleFormat::ALL {
858            assert_layout_matches(&format.urn(), &format.layout()).unwrap();
859            assert_eq!(SampleFormat::parse(format.as_str()), Some(*format));
860            assert_eq!(format.to_string(), format.as_str());
861        }
862        assert_eq!(SampleFormat::parse("nope"), None);
863    }
864
865    #[test]
866    fn compressed_images_conform_and_round_trip() {
867        assert_registry_layout_for::<CompressedImage>("std/media/v1/CompressedImage[format=jpeg]")
868            .unwrap();
869        let frame = CompressedImage::new("jpeg", vec![0xFF, 0xD8, 0xFF]);
870        let batch = frame.to_record_batch().unwrap();
871        assert_eq!(CompressedImage::from_record_batch(&batch).unwrap(), frame);
872        assert_eq!(frame.urn(), "std/media/v1/CompressedImage[format=jpeg]");
873        assert_eq!(CompressedImage::default().data.len(), 0);
874    }
875
876    #[test]
877    fn images_round_trip_in_every_sample_width() {
878        let cases = [
879            (
880                PixelFormat::Mono8,
881                ImageSamples::U8(vec![1, 2, 3, 4]),
882                2u32,
883                2u32,
884            ),
885            (
886                PixelFormat::Mono16,
887                ImageSamples::U16(vec![1, 2, 3, 4]),
888                2,
889                2,
890            ),
891            (PixelFormat::Rgb32F, ImageSamples::F32(vec![0.0; 12]), 2, 2),
892        ];
893        for (pixel, samples, width, height) in cases {
894            let frame = Image::new(pixel, width, height, samples).unwrap();
895            assert_layout_matches(&frame.urn(), &frame.layout()).unwrap();
896            let batch = frame.to_record_batch().unwrap();
897            let decoded = Image::from_record_batch(&batch).unwrap();
898            assert_eq!(decoded, frame, "{pixel}");
899            assert_eq!(decoded.channels(), pixel.channels());
900        }
901    }
902
903    #[test]
904    fn an_image_view_reads_the_same_payload() {
905        let frame =
906            Image::new(PixelFormat::Rgb8, 2, 2, ImageSamples::U8((0..12).collect())).unwrap();
907        let batch = frame.to_record_batch().unwrap();
908        let view = <ImageView as FromPayload>::from_batch(&batch).unwrap();
909        assert_eq!(view.width(), 2);
910        assert_eq!(view.height(), 2);
911        assert_eq!(view.channels(), 3);
912        assert_eq!(view.get_f64(&[0, 0, 0]).unwrap(), 0.0);
913    }
914
915    #[test]
916    fn a_mismatched_image_is_refused() {
917        let error = Image::new(PixelFormat::Mono8, 2, 2, ImageSamples::U8(vec![1, 2])).unwrap_err();
918        assert!(matches!(error, DataError::ChildLengthMismatch { .. }));
919
920        let error = Image::new(PixelFormat::Mono8, 1, 1, ImageSamples::F32(vec![1.0])).unwrap_err();
921        assert!(matches!(error, DataError::TypeMismatch { .. }));
922
923        assert!(ImageSamples::U8(Vec::new()).is_empty());
924        assert_eq!(ImageSamples::U16(vec![1, 2]).len(), 2);
925    }
926
927    #[test]
928    fn audio_frames_round_trip_through_every_sample_format() {
929        for format in SampleFormat::ALL {
930            let frame = AudioFrame::new(*format, 48_000, 2, vec![0.0, 0.5, -0.5, 1.0]).unwrap();
931            let batch = frame.to_record_batch().unwrap();
932            let decoded = AudioFrame::from_record_batch(&batch).unwrap();
933            assert_eq!(decoded.format, *format);
934            assert_eq!(decoded.sample_rate, 48_000);
935            assert_eq!(decoded.channels, 2);
936            assert_eq!(decoded.frame_count(), 2);
937            for (original, round_tripped) in frame.data.iter().zip(decoded.data.iter()) {
938                assert!(
939                    (original - round_tripped).abs() < 0.02,
940                    "{format}: {original} vs {round_tripped}"
941                );
942            }
943        }
944    }
945
946    #[test]
947    fn an_audio_frame_with_a_partial_interleave_is_refused() {
948        let error = AudioFrame::new(SampleFormat::F32, 48_000, 3, vec![0.0, 0.5]).unwrap_err();
949        assert!(matches!(error, DataError::ChildLengthMismatch { .. }));
950    }
951
952    #[test]
953    fn a_wrong_layout_is_refused() {
954        let compressed = CompressedImage::new("png", vec![1])
955            .to_record_batch()
956            .unwrap();
957        assert!(Image::from_record_batch(&compressed).is_err());
958        assert!(AudioFrame::from_record_batch(&compressed).is_err());
959        assert!(<ImageView as FromPayload>::from_batch(&compressed).is_err());
960
961        let image = Image::new(PixelFormat::Mono8, 1, 1, ImageSamples::U8(vec![7]))
962            .unwrap()
963            .to_record_batch()
964            .unwrap();
965        assert!(CompressedImage::from_record_batch(&image).is_err());
966    }
967
968    #[test]
969    fn strides_are_the_packed_row_length_in_bytes() {
970        assert_eq!(packed_stride(PixelFormat::Mono8, 640), 640);
971        assert_eq!(packed_stride(PixelFormat::Rgb8, 640), 1_920);
972        assert_eq!(packed_stride(PixelFormat::Rgba16, 640), 5_120);
973        assert_eq!(packed_stride(PixelFormat::Rgb32F, 640), 7_680);
974    }
975
976    #[test]
977    fn pixel_formats_are_recovered_from_their_columns() {
978        assert_eq!(pixel_for(&DataType::UInt8, 1), Some(PixelFormat::Mono8));
979        assert_eq!(pixel_for(&DataType::UInt8, 3), Some(PixelFormat::Rgb8));
980        assert_eq!(pixel_for(&DataType::Float32, 4), Some(PixelFormat::Rgba32F));
981        assert_eq!(pixel_for(&DataType::Int8, 1), None);
982        assert_eq!(pixel_for(&DataType::UInt8, 7), None);
983    }
984}