re_types_core/
as_components.rs

1use crate::{SerializationResult, SerializedComponentBatch};
2
3/// Describes the interface for interpreting an object as a bundle of [`Component`]s.
4///
5/// ## Custom bundles
6///
7/// While, in most cases, component bundles are code generated from our [IDL definitions],
8/// it is possible to manually extend existing bundles, or even implement fully custom ones.
9///
10/// All [`AsComponents`] methods are optional to implement, with the exception of
11/// [`AsComponents::as_serialized_batches`], which describes how the bundle can be interpreted
12/// as a set of [`SerializedComponentBatch`]es: serialized component data.
13///
14/// Have a look at our [Custom Data Loader] example to learn more about handwritten bundles.
15///
16/// [IDL definitions]: https://github.com/rerun-io/rerun/tree/latest/crates/store/re_types/definitions/rerun
17/// [Custom Data Loader]: https://github.com/rerun-io/rerun/blob/latest/examples/rust/custom_data_loader
18/// [`Component`]: [crate::Component]
19pub trait AsComponents {
20    /// Exposes the object's contents as a set of [`SerializedComponentBatch`]es.
21    ///
22    /// This is the main mechanism for easily extending builtin archetypes or even writing
23    /// fully custom ones.
24    /// Have a look at our [Custom Data Loader] example to learn more about extending archetypes.
25    ///
26    /// Implementers of [`AsComponents`] get one last chance to override the tags in the
27    /// [`ComponentDescriptor`], see [`SerializedComponentBatch::with_descriptor_override`].
28    ///
29    /// [Custom Data Loader]: https://github.com/rerun-io/rerun/blob/latest/docs/snippets/all/tutorials/custom_data.rs
30    /// [`ComponentDescriptor`]: [crate::ComponentDescriptor]
31    //
32    // NOTE: Don't bother returning a CoW here: we need to dynamically discard optional components
33    // depending on their presence (or lack thereof) at runtime anyway.
34    fn as_serialized_batches(&self) -> Vec<SerializedComponentBatch>;
35
36    // ---
37
38    /// Serializes all non-null [`Component`]s of this bundle into Arrow arrays.
39    ///
40    /// The default implementation will simply serialize the result of [`Self::as_serialized_batches`]
41    /// as-is, which is what you want in 99.9% of cases.
42    ///
43    /// [`Component`]: [crate::Component]
44    #[inline]
45    fn to_arrow(
46        &self,
47    ) -> SerializationResult<Vec<(::arrow::datatypes::Field, ::arrow::array::ArrayRef)>> {
48        self.as_serialized_batches()
49            .into_iter()
50            .map(|comp_batch| Ok((arrow::datatypes::Field::from(&comp_batch), comp_batch.array)))
51            .collect()
52    }
53}
54
55#[allow(dead_code)]
56fn assert_object_safe() {
57    let _: &dyn AsComponents;
58}
59
60impl AsComponents for SerializedComponentBatch {
61    #[inline]
62    fn as_serialized_batches(&self) -> Vec<SerializedComponentBatch> {
63        vec![self.clone()]
64    }
65}
66
67impl<AS: AsComponents, const N: usize> AsComponents for [AS; N] {
68    #[inline]
69    fn as_serialized_batches(&self) -> Vec<SerializedComponentBatch> {
70        self.iter()
71            .flat_map(|as_components| as_components.as_serialized_batches())
72            .collect()
73    }
74}
75
76impl<const N: usize> AsComponents for [&dyn AsComponents; N] {
77    #[inline]
78    fn as_serialized_batches(&self) -> Vec<SerializedComponentBatch> {
79        self.iter()
80            .flat_map(|as_components| as_components.as_serialized_batches())
81            .collect()
82    }
83}
84
85impl<const N: usize> AsComponents for [Box<dyn AsComponents>; N] {
86    #[inline]
87    fn as_serialized_batches(&self) -> Vec<SerializedComponentBatch> {
88        self.iter()
89            .flat_map(|as_components| as_components.as_serialized_batches())
90            .collect()
91    }
92}
93
94impl<AS: AsComponents> AsComponents for Vec<AS> {
95    #[inline]
96    fn as_serialized_batches(&self) -> Vec<SerializedComponentBatch> {
97        self.iter()
98            .flat_map(|as_components| as_components.as_serialized_batches())
99            .collect()
100    }
101}
102
103impl AsComponents for Vec<&dyn AsComponents> {
104    #[inline]
105    fn as_serialized_batches(&self) -> Vec<SerializedComponentBatch> {
106        self.iter()
107            .flat_map(|as_components| as_components.as_serialized_batches())
108            .collect()
109    }
110}
111
112impl AsComponents for Vec<Box<dyn AsComponents>> {
113    #[inline]
114    fn as_serialized_batches(&self) -> Vec<SerializedComponentBatch> {
115        self.iter()
116            .flat_map(|as_components| as_components.as_serialized_batches())
117            .collect()
118    }
119}
120
121// ---
122
123// NOTE: These needs to not be tests in order for doc-tests to work.
124
125/// ```compile_fail
126/// let comp = re_types_core::components::ClearIsRecursive::default();
127/// let _ = (&comp as &dyn re_types_core::AsComponents).as_serialized_batches();
128/// ```
129#[allow(dead_code)]
130#[allow(rustdoc::private_doc_tests)] // doc-tests are the only way to assert failed compilation
131fn single_ascomponents() {}
132
133/// ```compile_fail
134/// let comp = re_types_core::components::ClearIsRecursive::default();
135/// let _ = (&[comp] as &dyn re_types_core::AsComponents).as_serialized_batches();
136/// ```
137#[allow(dead_code)]
138#[allow(rustdoc::private_doc_tests)] // doc-tests are the only way to assert failed compilation
139fn single_ascomponents_wrapped() {
140    // This is non-sense (and more importantly: dangerous): a single component shouldn't be able to
141    // autocast straight to a collection of batches.
142}
143
144/// ```compile_fail
145/// let comp = re_types_core::components::ClearIsRecursive::default();
146/// let _ = (&[comp, comp, comp] as &dyn re_types_core::AsComponents).as_serialized_batches();
147/// ```
148#[allow(dead_code)]
149#[allow(rustdoc::private_doc_tests)] // doc-tests are the only way to assert failed compilation
150fn single_ascomponents_wrapped_many() {
151    // This is non-sense (and more importantly: dangerous): a single component shouldn't be able to
152    // autocast straight to a collection of batches.
153}
154
155/// ```compile_fail
156/// let comp = re_types_core::components::ClearIsRecursive::default();
157/// let comps = vec![comp, comp, comp];
158/// let _ = (&comps as &dyn re_types_core::AsComponents).as_serialized_batches();
159/// ```
160#[allow(dead_code)]
161#[allow(rustdoc::private_doc_tests)] // doc-tests are the only way to assert failed compilation
162fn many_ascomponents() {}
163
164/// ```compile_fail
165/// let comp = re_types_core::components::ClearIsRecursive::default();
166/// let comps = vec![comp, comp, comp];
167/// let _ = (&[comps] as &dyn re_types_core::AsComponents).as_serialized_batches();
168/// ```
169#[allow(dead_code)]
170#[allow(rustdoc::private_doc_tests)] // doc-tests are the only way to assert failed compilation
171fn many_ascomponents_wrapped() {}
172
173/// ```compile_fail
174/// let comp = re_types_core::components::ClearIsRecursive::default();
175/// let comps = vec![comp, comp, comp];
176/// let _ = (&[comps] as &dyn re_types_core::ComponentBatch).to_arrow();
177/// ```
178#[allow(dead_code)]
179#[allow(rustdoc::private_doc_tests)] // doc-tests are the only way to assert failed compilation
180fn many_componentbatch_wrapped() {}
181
182/// ```compile_fail
183/// let comp = re_types_core::components::ClearIsRecursive::default();
184/// let comps = vec![comp, comp, comp];
185/// let _ = (&[comps.clone(), comps.clone(), comps.clone()] as &dyn re_types_core::AsComponents).as_serialized_batches();
186/// ```
187#[allow(dead_code)]
188#[allow(rustdoc::private_doc_tests)] // doc-tests are the only way to assert failed compilation
189fn many_ascomponents_wrapped_many() {}
190
191/// ```compile_fail
192/// let comp = re_types_core::components::ClearIsRecursive::default();
193/// let comps = vec![comp, comp, comp];
194/// let _ = (&[comps.clone(), comps.clone(), comps.clone()] as &dyn re_types_core::ComponentBatch).to_arrow();
195/// ```
196#[allow(dead_code)]
197#[allow(rustdoc::private_doc_tests)] // doc-tests are the only way to assert failed compilation
198fn many_componentbatch_wrapped_many() {}
199
200#[cfg(test)]
201mod tests {
202    use std::sync::Arc;
203
204    use arrow::array::{
205        types::UInt32Type, Array as ArrowArray, PrimitiveArray as ArrowPrimitiveArray,
206    };
207    use itertools::Itertools as _;
208    use similar_asserts::assert_eq;
209
210    #[derive(Clone, Copy, Debug, PartialEq, Eq, bytemuck::Pod, bytemuck::Zeroable)]
211    #[repr(transparent)]
212    pub struct MyColor(pub u32);
213
214    crate::macros::impl_into_cow!(MyColor);
215
216    impl re_byte_size::SizeBytes for MyColor {
217        #[inline]
218        fn heap_size_bytes(&self) -> u64 {
219            let Self(_) = self;
220            0
221        }
222    }
223
224    impl crate::Loggable for MyColor {
225        fn arrow_datatype() -> arrow::datatypes::DataType {
226            arrow::datatypes::DataType::UInt32
227        }
228
229        fn to_arrow_opt<'a>(
230            data: impl IntoIterator<Item = Option<impl Into<std::borrow::Cow<'a, Self>>>>,
231        ) -> crate::SerializationResult<arrow::array::ArrayRef>
232        where
233            Self: 'a,
234        {
235            use crate::datatypes::UInt32;
236            UInt32::to_arrow_opt(
237                data.into_iter()
238                    .map(|opt| opt.map(Into::into).map(|c| UInt32(c.0))),
239            )
240        }
241
242        fn from_arrow_opt(
243            data: &dyn arrow::array::Array,
244        ) -> crate::DeserializationResult<Vec<Option<Self>>> {
245            use crate::datatypes::UInt32;
246            Ok(UInt32::from_arrow_opt(data)?
247                .into_iter()
248                .map(|opt| opt.map(|v| Self(v.0)))
249                .collect())
250        }
251    }
252
253    impl crate::Component for MyColor {
254        fn descriptor() -> crate::ComponentDescriptor {
255            crate::ComponentDescriptor::new("example.MyColor")
256        }
257    }
258
259    #[allow(dead_code)]
260    fn data() -> (MyColor, MyColor, MyColor, Vec<MyColor>) {
261        let red = MyColor(0xDD0000FF);
262        let green = MyColor(0x00DD00FF);
263        let blue = MyColor(0x0000DDFF);
264        let colors = vec![red, green, blue];
265        (red, green, blue, colors)
266    }
267
268    #[test]
269    fn single_ascomponents_howto() {
270        let (red, _, _, _) = data();
271
272        let got = {
273            let red = &red as &dyn crate::ComponentBatch;
274            vec![red.try_serialized().unwrap().array]
275        };
276        let expected = vec![
277            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>,
278        ];
279        assert_eq!(&expected, &got);
280    }
281
282    #[test]
283    fn single_componentbatch() -> anyhow::Result<()> {
284        let (red, _, _, _) = data();
285
286        // A single component should autocast to a batch with a single instance.
287        let got = (&red as &dyn crate::ComponentBatch).to_arrow()?;
288        let expected =
289            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>;
290        similar_asserts::assert_eq!(&expected, &got);
291
292        Ok(())
293    }
294
295    #[test]
296    fn single_ascomponents_wrapped_howto() {
297        let (red, _, _, _) = data();
298
299        let got = {
300            let red = &red as &dyn crate::ComponentBatch;
301            vec![red.try_serialized().unwrap().array]
302        };
303        let expected = vec![
304            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>,
305        ];
306        assert_eq!(&expected, &got);
307    }
308
309    #[test]
310    fn single_componentbatch_wrapped() -> anyhow::Result<()> {
311        let (red, _, _, _) = data();
312
313        // Nothing out of the ordinary here, a slice of components is indeed a batch.
314        let got = (&[red] as &dyn crate::ComponentBatch).to_arrow()?;
315        let expected =
316            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>;
317        similar_asserts::assert_eq!(&expected, &got);
318
319        Ok(())
320    }
321
322    #[test]
323    fn single_ascomponents_wrapped_many_howto() {
324        let (red, green, blue, _) = data();
325
326        let got = {
327            let red = &red as &dyn crate::ComponentBatch;
328            let green = &green as &dyn crate::ComponentBatch;
329            let blue = &blue as &dyn crate::ComponentBatch;
330            [
331                red.try_serialized().unwrap(),
332                green.try_serialized().unwrap(),
333                blue.try_serialized().unwrap(),
334            ]
335            .into_iter()
336            .map(|batch| batch.array)
337            .collect_vec()
338        };
339        let expected = vec![
340            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>,
341            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![green.0])) as Arc<dyn ArrowArray>,
342            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![blue.0])) as Arc<dyn ArrowArray>,
343        ];
344        assert_eq!(&expected, &got);
345    }
346
347    #[test]
348    fn single_componentbatch_wrapped_many() -> anyhow::Result<()> {
349        let (red, green, blue, _) = data();
350
351        // Nothing out of the ordinary here, a slice of components is indeed a batch.
352        let got = (&[red, green, blue] as &dyn crate::ComponentBatch).to_arrow()?;
353        let expected = Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
354            red.0, green.0, blue.0,
355        ])) as Arc<dyn ArrowArray>;
356        similar_asserts::assert_eq!(&expected, &got);
357
358        Ok(())
359    }
360
361    #[test]
362    fn many_componentbatch() -> anyhow::Result<()> {
363        let (red, green, blue, colors) = data();
364
365        // Nothing out of the ordinary here, a batch is indeed a batch.
366        let got = (&colors as &dyn crate::ComponentBatch).to_arrow()?;
367        let expected = Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
368            red.0, green.0, blue.0,
369        ])) as Arc<dyn ArrowArray>;
370        similar_asserts::assert_eq!(&expected, &got);
371
372        Ok(())
373    }
374
375    #[test]
376    fn many_ascomponents_wrapped_howto() {
377        let (red, green, blue, colors) = data();
378
379        let got = {
380            let colors = &colors as &dyn crate::ComponentBatch;
381            vec![colors.try_serialized().unwrap().array]
382        };
383        let expected = vec![Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
384            red.0, green.0, blue.0,
385        ])) as Arc<dyn ArrowArray>];
386        assert_eq!(&expected, &got);
387    }
388
389    #[test]
390    fn many_ascomponents_wrapped_many_howto() {
391        let (red, green, blue, colors) = data();
392
393        // Nothing out of the ordinary here, a collection of batches is indeed a collection of batches.
394        let got = {
395            let colors = &colors as &dyn crate::ComponentBatch;
396            vec![
397                colors.try_serialized().unwrap().array,
398                colors.try_serialized().unwrap().array,
399                colors.try_serialized().unwrap().array,
400            ]
401        };
402        let expected = vec![
403            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
404                red.0, green.0, blue.0,
405            ])) as Arc<dyn ArrowArray>,
406            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
407                red.0, green.0, blue.0,
408            ])) as Arc<dyn ArrowArray>,
409            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
410                red.0, green.0, blue.0,
411            ])) as Arc<dyn ArrowArray>,
412        ];
413        assert_eq!(&expected, &got);
414    }
415}
re_types_core/as_components.rs

re_types_core/
as_components.rs
