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    use crate::{Component as _, ComponentDescriptor};
211
212    #[derive(Clone, Copy, Debug, PartialEq, Eq, bytemuck::Pod, bytemuck::Zeroable)]
213    #[repr(transparent)]
214    pub struct MyColor(pub u32);
215
216    impl MyColor {
217        fn descriptor() -> ComponentDescriptor {
218            ComponentDescriptor {
219                archetype: Some("test".into()),
220                component: "color".into(),
221                component_type: Some(Self::name()),
222            }
223        }
224    }
225
226    crate::macros::impl_into_cow!(MyColor);
227
228    impl re_byte_size::SizeBytes for MyColor {
229        #[inline]
230        fn heap_size_bytes(&self) -> u64 {
231            let Self(_) = self;
232            0
233        }
234    }
235
236    impl crate::Loggable for MyColor {
237        fn arrow_datatype() -> arrow::datatypes::DataType {
238            arrow::datatypes::DataType::UInt32
239        }
240
241        fn to_arrow_opt<'a>(
242            data: impl IntoIterator<Item = Option<impl Into<std::borrow::Cow<'a, Self>>>>,
243        ) -> crate::SerializationResult<arrow::array::ArrayRef>
244        where
245            Self: 'a,
246        {
247            use crate::datatypes::UInt32;
248            UInt32::to_arrow_opt(
249                data.into_iter()
250                    .map(|opt| opt.map(Into::into).map(|c| UInt32(c.0))),
251            )
252        }
253
254        fn from_arrow_opt(
255            data: &dyn arrow::array::Array,
256        ) -> crate::DeserializationResult<Vec<Option<Self>>> {
257            use crate::datatypes::UInt32;
258            Ok(UInt32::from_arrow_opt(data)?
259                .into_iter()
260                .map(|opt| opt.map(|v| Self(v.0)))
261                .collect())
262        }
263    }
264
265    impl crate::Component for MyColor {
266        fn name() -> crate::ComponentType {
267            "example.MyColor".into()
268        }
269    }
270
271    #[allow(dead_code)]
272    fn data() -> (MyColor, MyColor, MyColor, Vec<MyColor>) {
273        let red = MyColor(0xDD0000FF);
274        let green = MyColor(0x00DD00FF);
275        let blue = MyColor(0x0000DDFF);
276        let colors = vec![red, green, blue];
277        (red, green, blue, colors)
278    }
279
280    #[test]
281    fn single_ascomponents_howto() {
282        let (red, _, _, _) = data();
283
284        let got = {
285            let red = &red as &dyn crate::ComponentBatch;
286            vec![red.try_serialized(MyColor::descriptor()).unwrap().array]
287        };
288        let expected = vec![
289            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>,
290        ];
291        assert_eq!(&expected, &got);
292    }
293
294    #[test]
295    fn single_componentbatch() -> anyhow::Result<()> {
296        let (red, _, _, _) = data();
297
298        // A single component should autocast to a batch with a single instance.
299        let got = (&red as &dyn crate::ComponentBatch).to_arrow()?;
300        let expected =
301            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>;
302        similar_asserts::assert_eq!(&expected, &got);
303
304        Ok(())
305    }
306
307    #[test]
308    fn single_ascomponents_wrapped_howto() {
309        let (red, _, _, _) = data();
310
311        let got = {
312            let red = &red as &dyn crate::ComponentBatch;
313            vec![red.try_serialized(MyColor::descriptor()).unwrap().array]
314        };
315        let expected = vec![
316            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>,
317        ];
318        assert_eq!(&expected, &got);
319    }
320
321    #[test]
322    fn single_componentbatch_wrapped() -> anyhow::Result<()> {
323        let (red, _, _, _) = data();
324
325        // Nothing out of the ordinary here, a slice of components is indeed a batch.
326        let got = (&[red] as &dyn crate::ComponentBatch).to_arrow()?;
327        let expected =
328            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>;
329        similar_asserts::assert_eq!(&expected, &got);
330
331        Ok(())
332    }
333
334    #[test]
335    fn single_ascomponents_wrapped_many_howto() {
336        let (red, green, blue, _) = data();
337
338        let got = {
339            let red = &red as &dyn crate::ComponentBatch;
340            let green = &green as &dyn crate::ComponentBatch;
341            let blue = &blue as &dyn crate::ComponentBatch;
342            [
343                red.try_serialized(MyColor::descriptor()).unwrap(),
344                green.try_serialized(MyColor::descriptor()).unwrap(),
345                blue.try_serialized(MyColor::descriptor()).unwrap(),
346            ]
347            .into_iter()
348            .map(|batch| batch.array)
349            .collect_vec()
350        };
351        let expected = vec![
352            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![red.0])) as Arc<dyn ArrowArray>,
353            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![green.0])) as Arc<dyn ArrowArray>,
354            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![blue.0])) as Arc<dyn ArrowArray>,
355        ];
356        assert_eq!(&expected, &got);
357    }
358
359    #[test]
360    fn single_componentbatch_wrapped_many() -> anyhow::Result<()> {
361        let (red, green, blue, _) = data();
362
363        // Nothing out of the ordinary here, a slice of components is indeed a batch.
364        let got = (&[red, green, blue] as &dyn crate::ComponentBatch).to_arrow()?;
365        let expected = Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
366            red.0, green.0, blue.0,
367        ])) as Arc<dyn ArrowArray>;
368        similar_asserts::assert_eq!(&expected, &got);
369
370        Ok(())
371    }
372
373    #[test]
374    fn many_componentbatch() -> anyhow::Result<()> {
375        let (red, green, blue, colors) = data();
376
377        // Nothing out of the ordinary here, a batch is indeed a batch.
378        let got = (&colors as &dyn crate::ComponentBatch).to_arrow()?;
379        let expected = Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
380            red.0, green.0, blue.0,
381        ])) as Arc<dyn ArrowArray>;
382        similar_asserts::assert_eq!(&expected, &got);
383
384        Ok(())
385    }
386
387    #[test]
388    fn many_ascomponents_wrapped_howto() {
389        let (red, green, blue, colors) = data();
390
391        let got = {
392            let colors = &colors as &dyn crate::ComponentBatch;
393            vec![colors.try_serialized(MyColor::descriptor()).unwrap().array]
394        };
395        let expected = vec![Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
396            red.0, green.0, blue.0,
397        ])) as Arc<dyn ArrowArray>];
398        assert_eq!(&expected, &got);
399    }
400
401    #[test]
402    fn many_ascomponents_wrapped_many_howto() {
403        let (red, green, blue, colors) = data();
404
405        // Nothing out of the ordinary here, a collection of batches is indeed a collection of batches.
406        let got = {
407            let colors = &colors as &dyn crate::ComponentBatch;
408            vec![
409                colors.try_serialized(MyColor::descriptor()).unwrap().array,
410                colors.try_serialized(MyColor::descriptor()).unwrap().array,
411                colors.try_serialized(MyColor::descriptor()).unwrap().array,
412            ]
413        };
414        let expected = vec![
415            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
416                red.0, green.0, blue.0,
417            ])) as Arc<dyn ArrowArray>,
418            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
419                red.0, green.0, blue.0,
420            ])) as Arc<dyn ArrowArray>,
421            Arc::new(ArrowPrimitiveArray::<UInt32Type>::from(vec![
422                red.0, green.0, blue.0,
423            ])) as Arc<dyn ArrowArray>,
424        ];
425        assert_eq!(&expected, &got);
426    }
427}
re_types_core/as_components.rs

re_types_core/
as_components.rs
