Rerun C++ SDK
Loading...
Searching...
No Matches
component_batch.hpp
1#pragma once
2
3#include <memory> // shared_ptr
4#include <optional>
5#include <unordered_map>
6
7#include "collection.hpp"
8#include "component_descriptor.hpp"
9#include "component_type.hpp"
10#include "error.hpp"
11#include "loggable.hpp"
12
13namespace arrow {
14 class Array;
15 class DataType;
16} // namespace arrow
17
18struct rr_component_batch;
19
20namespace rerun {
21 struct ComponentColumn;
22}
23
24namespace rerun {
25 /// Arrow-encoded data of a single batch of components together with a component descriptor.
26 ///
27 /// Component descriptors are registered when first encountered.
29 /// Arrow-encoded data of the component instances.
30 std::shared_ptr<arrow::Array> array;
31
32 /// The type of the component instances in array.
34
35 public:
36 /// Creates a new empty component batch with a given descriptor.
37 template <typename T>
39 return from_loggable(Collection<T>(), descriptor);
40 }
41
42 /// Creates a new component batch from a collection of component instances.
43 ///
44 /// Automatically registers the descriptor the first time it is encountered.
45 template <typename T>
47 const rerun::Collection<T>& components, const ComponentDescriptor& descriptor
48 ) {
49 static_assert(
50 rerun::is_loggable<T>,
51 "The given type does not implement the rerun::Loggable trait."
52 );
53
54 /// TODO(#4257) should take a rerun::Collection instead of pointer and size.
55 auto array = Loggable<T>::to_arrow(components.data(), components.size());
56 RR_RETURN_NOT_OK(array.error);
57
58 return from_arrow_array(std::move(array.value), descriptor);
59 }
60
61 /// Creates a new component batch from a single component instance.
62 ///
63 /// Automatically registers the descriptor the first time it is encountered.
64 template <typename T>
66 const T& component, const ComponentDescriptor& descriptor
67 ) {
68 // Collection adapter will automatically borrow for single elements, but let's do this explicitly, avoiding the extra hoop.
69 const auto collection = Collection<T>::borrow(&component, 1);
70 return from_loggable(collection, descriptor);
71 }
72
73 /// Creates a new data cell from a single optional component instance.
74 ///
75 /// None is represented as a data cell with 0 instances.
76 ///
77 /// Automatically registers the descriptor the first time it is encountered.
78 template <typename T>
80 const std::optional<T>& component, const ComponentDescriptor& descriptor
81 ) {
82 if (component.has_value()) {
83 return from_loggable(component.value(), descriptor);
84 } else {
85 return from_loggable(Collection<T>(), descriptor);
86 }
87 }
88
89 /// Creates a new data cell from an optional collection of component instances.
90 ///
91 /// None is represented as a data cell with 0 instances.
92 ///
93 /// Automatically registers the descriptor the first time it is encountered.
94 template <typename T>
96 const std::optional<rerun::Collection<T>>& components,
97 const ComponentDescriptor& descriptor
98 ) {
99 if (components.has_value()) {
100 return from_loggable(components.value(), descriptor);
101 } else {
102 return from_loggable(Collection<T>(), descriptor);
103 }
104 }
105
106 /// Creates a new component batch for an archetype indicator.
107 template <typename Archetype>
110 typename Archetype::IndicatorComponent(),
112 );
113 }
114
115 /// Creates a new component batch from an already existing arrow array.
116 ///
117 /// Automatically registers the descriptor the first time it is encountered.
119 std::shared_ptr<arrow::Array> array, const ComponentDescriptor& descriptor
120 );
121
122 /// Partitions the component data into multiple sub-batches.
123 ///
124 /// Specifically, this transforms the existing `ComponentBatch` data into a `ComponentColumn`.
125 ///
126 /// This makes it possible to use `RecordingStream::send_columns` to send columnar data directly into Rerun.
127 ///
128 /// \param lengths The number of components in each run. for `rerun::RecordingStream::send_columns`,
129 /// this specifies the number of components at each time point.
130 /// The sum of the lengths must be equal to the number of components in the batch.
132
133 /// Partitions the component data into unit-length sub-batches.
134 ///
135 /// Specifically, this transforms the existing `ComponentBatch` data into a `ComponentColumn`.
136 /// This makes it possible to use `RecordingStream::send_columns` to send columnar data directly into Rerun.
138
139 /// Partitions the component data into multiple sub-batches.
140 ///
141 /// Specifically, this transforms the existing `ComponentBatch` data into a `ComponentColumn`.
142 /// This makes it possible to use `RecordingStream::send_columns` to send columnar data directly into Rerun.
143 ///
144 /// \param lengths The number of components in each run. for `rerun::RecordingStream::send_columns`,
145 /// this specifies the number of components at each time point.
146 /// The sum of the lengths must be equal to the number of components in the batch.
148
149 /// Partitions the component data into unit-length sub-batches.
150 ///
151 /// Specifically, this transforms the existing `ComponentBatch` data into a `ComponentColumn`.
152 /// This makes it possible to use `RecordingStream::send_columns` to send columnar data directly into Rerun.
154
155 /// Size in the number of elements the underlying arrow array contains.
156 size_t length() const;
157
158 /// To rerun C API component batch.
159 ///
160 /// The resulting `rr_component_batch` keeps the `arrow::Array` alive until it is released.
161 Error to_c_ffi_struct(rr_component_batch& out_component_batch) const;
162 };
163} // namespace rerun
Generic collection of elements that are roughly contiguous in memory.
Definition collection.hpp:49
static Collection< TElement > borrow(const T *data, size_t num_instances=1)
Borrows binary compatible data into the collection from a typed pointer.
Definition collection.hpp:154
size_t size() const
Returns the number of instances in this collection.
Definition collection.hpp:291
const TElement * data() const
Returns a raw pointer to the underlying data.
Definition collection.hpp:327
Status outcome object (success or error) returned for fallible operations.
Definition error.hpp:99
A class for representing either a usable value, or an error.
Definition result.hpp:14
All Rerun C++ types and functions are in the rerun namespace or one of its nested namespaces.
Definition rerun.hpp:23
uint32_t ComponentTypeHandle
Handle to a registered component types.
Definition component_type.hpp:14
Arrow-encoded data of a single batch of components together with a component descriptor.
Definition component_batch.hpp:28
Result< ComponentColumn > partitioned() const &
Partitions the component data into unit-length sub-batches.
static Result< ComponentBatch > from_loggable(const T &component, const ComponentDescriptor &descriptor)
Creates a new component batch from a single component instance.
Definition component_batch.hpp:65
size_t length() const
Size in the number of elements the underlying arrow array contains.
static Result< ComponentBatch > empty(const ComponentDescriptor &descriptor)
Creates a new empty component batch with a given descriptor.
Definition component_batch.hpp:38
Error to_c_ffi_struct(rr_component_batch &out_component_batch) const
To rerun C API component batch.
static Result< ComponentBatch > from_loggable(const rerun::Collection< T > &components, const ComponentDescriptor &descriptor)
Creates a new component batch from a collection of component instances.
Definition component_batch.hpp:46
static Result< ComponentBatch > from_loggable(const std::optional< rerun::Collection< T > > &components, const ComponentDescriptor &descriptor)
Creates a new data cell from an optional collection of component instances.
Definition component_batch.hpp:95
Result< ComponentColumn > partitioned(const Collection< uint32_t > &lengths) &&
Partitions the component data into multiple sub-batches.
ComponentTypeHandle component_type
The type of the component instances in array.
Definition component_batch.hpp:33
static Result< ComponentBatch > from_loggable(const std::optional< T > &component, const ComponentDescriptor &descriptor)
Creates a new data cell from a single optional component instance.
Definition component_batch.hpp:79
static Result< ComponentBatch > from_arrow_array(std::shared_ptr< arrow::Array > array, const ComponentDescriptor &descriptor)
Creates a new component batch from an already existing arrow array.
std::shared_ptr< arrow::Array > array
Arrow-encoded data of the component instances.
Definition component_batch.hpp:30
static Result< ComponentBatch > from_indicator()
Creates a new component batch for an archetype indicator.
Definition component_batch.hpp:108
Result< ComponentColumn > partitioned() &&
Partitions the component data into unit-length sub-batches.
Result< ComponentColumn > partitioned(const Collection< uint32_t > &lengths) const &
Partitions the component data into multiple sub-batches.
A ComponentDescriptor fully describes the semantics of a column of data.
Definition component_descriptor.hpp:14
The Loggable trait is used by all built-in implementation of rerun::AsComponents to serialize a colle...
Definition loggable.hpp:11