Rerun C++ SDK
Loading...
Searching...
No Matches
component_column.hpp
1#pragma once
2
3#include <cstddef> // size_t
4#include <memory> // shared_ptr
5
6#include "collection.hpp"
7#include "component_batch.hpp"
8#include "component_type.hpp"
9#include "error.hpp"
10#include "loggable.hpp"
11
12namespace arrow {
13 class Buffer;
14}
15
16struct rr_component_column;
17
18namespace rerun {
19 namespace detail {
20 /// Builds a shareable buffer of cumulative uint32_t offsets, starting at zero.
21 /// Accumulation does not check for overflow.
22 std::shared_ptr<arrow::Buffer> offsets_from_lengths(const Collection<uint32_t>& lengths);
23 } // namespace detail
24
25 /// Arrow-encoded data of a column of components.
26 ///
27 /// This is essentially an array of `rerun::ComponentBatch` with all batches
28 /// continuously in a single array.
29 ///
30 /// \see `rerun::RecordingStream::send_columns`
32 /// Arrow-encoded list array of component batches.
33 std::shared_ptr<arrow::Array> array;
34
35 /// The type of the component instances in array.
37
38 public:
39 /// Creates a new component column from a collection of component instances.
40 ///
41 /// Automatically registers the component type the first time this type is encountered.
42 ///
43 /// \param components Continuous collection of components which is about to be partitioned.
44 /// \param lengths The number of components in each run. for `rerun::RecordingStream::send_columns`,
45 /// this specifies the number of components at each time point.
46 /// The sum of the lengths must be equal to the number of components in the batch.
47 /// \param descriptor Descriptor of the component type for this column.
48 template <typename T>
50 const Collection<T>& components, const Collection<uint32_t>& lengths,
52 ) {
53 auto component_batch_result = ComponentBatch::from_loggable(components, descriptor);
54 if (component_batch_result.is_err()) {
55 return component_batch_result.error;
56 }
57 return from_batch_with_lengths(component_batch_result.value, lengths);
58 }
59
60 /// Creates a new component column from a collection of component instances where each run has a length of one.
61 ///
62 /// When used with `rerun::RecordingStream::send_columns`, this is equivalent to `from_loggable(components, std::vector{1, 1, ...})`.
63 /// I.e. there's a single component for each time point.
64 ///
65 /// Automatically registers the component type the first time this type is encountered.
66 ///
67 /// \param components Continuous collection of components which is about to be partitioned into runs of length one.
68 /// \param descriptor Descriptor of the component type for this column.
69 template <typename T>
71 const Collection<T>& components,
73 ) {
75 components,
76 Collection<uint32_t>::take_ownership(std::vector<uint32_t>(components.size(), 1)),
77 descriptor
78 );
79 }
80
81 /// Creates a new component batch partition from a batch and a collection of run lengths.
82 ///
83 /// \param batch A batch of components which is about to be partitioned.
84 /// \param lengths The number of components in each run. for `rerun::RecordingStream::send_columns`,
85 /// this specifies the number of components at each time point.
86 /// The sum of the lengths must be equal to the number of components in the batch.
88 ComponentBatch batch, const Collection<uint32_t>& lengths
89 );
90
91 /// Creates a new component batch partition from a batch and a collection of component offsets.
92 ///
93 /// \param batch A batch of components which is about to be partitioned.
94 /// \param offsets An offset within `batch` for each array of components.
95 /// The last offset is the total number of components in the batch. Meaning that this array has to be
96 /// one element longer than the number of component runs.
97 /// E.g. a `PartitionedComponentBatch` with a single component would have an offset array of `[0, 1]`.
98 /// A `ComponentColumn` with 5 components divided into runs of length 2 and 3
99 // would have an offset array of `[0, 2, 5]`.
102 );
103
104 /// Creates a new component batch partition from a batch and a shared Arrow offsets buffer.
105 ///
106 /// The column shares ownership of the offsets buffer and the batch's values without copying them,
107 /// and retains the batch's component type handle.
108 /// Multiple columns can share the same offsets buffer.
109 ///
110 /// \param batch A batch of components which is about to be partitioned.
111 /// \param offsets A non-null buffer containing `num_rows + 1` contiguous uint32_t offsets into `batch`.
112 /// Offsets must start at zero, be nondecreasing, and end at the total number of components in the batch.
113 /// Equal consecutive offsets produce an empty row.
114 /// For example, five components divided into two rows of lengths two and three use `[0, 2, 5]`.
115 /// The buffer must not be modified while any column uses it.
116 /// \param num_rows The number of component runs (rows), one less than the number of offsets.
117 ///
118 /// The caller must supply valid Arrow list offsets; this method does not validate them.
120 ComponentBatch batch, std::shared_ptr<arrow::Buffer> offsets, size_t num_rows
121 );
122
123 /// To rerun C API component batch.
124 ///
125 /// The resulting `rr_component_column` keeps the `arrow::Array` alive until it is released.
126 Error to_c_ffi_struct(rr_component_column& out_component_batch) const;
127 };
128} // namespace rerun
Generic collection of elements that are roughly contiguous in memory.
Definition collection.hpp:49
size_t size() const
Returns the number of instances in this collection.
Definition collection.hpp:295
Status outcome object (success or error) returned for fallible operations.
Definition error.hpp:104
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:26
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
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
Arrow-encoded data of a column of components.
Definition component_column.hpp:31
static Result< ComponentColumn > from_loggable(const Collection< T > &components, const ComponentDescriptor &descriptor=rerun::Loggable< T >::Descriptor)
Creates a new component column from a collection of component instances where each run has a length o...
Definition component_column.hpp:70
static Result< ComponentColumn > from_loggable_with_lengths(const Collection< T > &components, const Collection< uint32_t > &lengths, const ComponentDescriptor &descriptor=rerun::Loggable< T >::Descriptor)
Creates a new component column from a collection of component instances.
Definition component_column.hpp:49
static Result< ComponentColumn > from_batch_with_offsets(ComponentBatch batch, std::shared_ptr< arrow::Buffer > offsets, size_t num_rows)
Creates a new component batch partition from a batch and a shared Arrow offsets buffer.
ComponentTypeHandle component_type
The type of the component instances in array.
Definition component_column.hpp:36
static Result< ComponentColumn > from_batch_with_lengths(ComponentBatch batch, const Collection< uint32_t > &lengths)
Creates a new component batch partition from a batch and a collection of run lengths.
std::shared_ptr< arrow::Array > array
Arrow-encoded list array of component batches.
Definition component_column.hpp:33
static Result< ComponentColumn > from_batch_with_offsets(ComponentBatch batch, Collection< uint32_t > offsets)
Creates a new component batch partition from a batch and a collection of component offsets.
Error to_c_ffi_struct(rr_component_column &out_component_batch) const
To rerun C API component batch.
A ComponentDescriptor fully describes the semantics of a column of data.
Definition component_descriptor.hpp:16
The Loggable trait is used by all built-in implementation of rerun::AsComponents to serialize a colle...
Definition loggable.hpp:11