Implement new lens kinds OneToOne, Static, and OneToMany

Rethink target entity paths

Clean up terminology: `Timeline` vs `Time`

Author: grtlr

crates/top/re_sdk/src/lenses/ast.rs

@@ -0,0 +1,326 @@
+//! Builder API for constructing lenses.
+
+use re_chunk::{ComponentIdentifier, EntityPath, TimelineName};
+use re_log_types::{EntityPathFilter, TimeType};
+use re_types::ComponentDescriptor;
+
+use super::Op;
+use super::ast;
+
+/// Builder for lenses with support for multiple output modes.
+pub struct LensBuilder {
+    input: ast::InputColumn,
+    outputs: Vec<ast::LensKind>,
+}
+
+impl LensBuilder {
+    pub(crate) fn new(
+        entity_path_filter: EntityPathFilter,
+        component: impl Into<ComponentIdentifier>,
+    ) -> Self {
+        Self {
+            input: ast::InputColumn {
+                entity_path_filter,
+                component: component.into(),
+            },
+            outputs: vec![],
+        }
+    }
+
+    /// Adds a temporal output with 1:1 row mapping.
+    ///
+    /// Each input row produces exactly one output row. Outputs inherit time columns from
+    /// the input, plus any additional time columns specified via `.time()`.
+    ///
+    /// The output will use the same entity path as the input.
+    pub fn output_columns(mut self, builder: impl FnOnce(ColumnsBuilder) -> ColumnsBuilder) -> Self {
+        let output_builder = ColumnsBuilder::new(ast::TargetEntity::SameAsInput);
+        let output = builder(output_builder).build();
+        self.outputs.push(output);
+        self
+    }
+
+    /// Adds a temporal output with 1:1 row mapping at a specific entity path.
+    ///
+    /// Each input row produces exactly one output row. Outputs inherit time columns from
+    /// the input, plus any additional time columns specified via `.time()`.
+    pub fn output_columns_at(
+        mut self,
+        entity_path: impl Into<EntityPath>,
+        builder: impl FnOnce(ColumnsBuilder) -> ColumnsBuilder,
+    ) -> Self {
+        let output_builder =
+            ColumnsBuilder::new(ast::TargetEntity::Explicit(entity_path.into()));
+        let output = builder(output_builder).build();
+        self.outputs.push(output);
+        self
+    }
+
+    /// Adds a static output (timeless data).
+    ///
+    /// Creates data that does not change over time and has no associated time columns.
+    ///
+    /// The output will use the same entity path as the input.
+    pub fn output_static_columns(
+        mut self,
+        builder: impl FnOnce(StaticColumnsBuilder) -> StaticColumnsBuilder,
+    ) -> Self {
+        let output_builder = StaticColumnsBuilder::new(ast::TargetEntity::SameAsInput);
+        let output = builder(output_builder).build();
+        self.outputs.push(output);
+        self
+    }
+
+    /// Adds a static output (timeless data) at a specific entity path.
+    ///
+    /// Creates data that does not change over time and has no associated time columns.
+    pub fn output_static_columns_at(
+        mut self,
+        entity_path: impl Into<EntityPath>,
+        builder: impl FnOnce(StaticColumnsBuilder) -> StaticColumnsBuilder,
+    ) -> Self {
+        let output_builder =
+            StaticColumnsBuilder::new(ast::TargetEntity::Explicit(entity_path.into()));
+        let output = builder(output_builder).build();
+        self.outputs.push(output);
+        self
+    }
+
+    /// Adds a temporal output with 1:N row mapping (scatter).
+    ///
+    /// Each input row produces multiple output rows at the same timepoint. The timepoint
+    /// is replicated/scattered across the output rows. Useful for flattening lists or
+    /// exploding batches.
+    ///
+    /// The output will use the same entity path as the input.
+    pub fn output_scatter_columns(
+        mut self,
+        builder: impl FnOnce(ScatterColumnsBuilder) -> ScatterColumnsBuilder,
+    ) -> Self {
+        let output_builder = ScatterColumnsBuilder::new(ast::TargetEntity::SameAsInput);
+        let output = builder(output_builder).build();
+        self.outputs.push(output);
+        self
+    }
+
+    /// Adds a temporal output with 1:N row mapping (scatter) at a specific entity path.
+    ///
+    /// Each input row produces multiple output rows at the same timepoint. The timepoint
+    /// is replicated/scattered across the output rows. Useful for flattening lists or
+    /// exploding batches.
+    pub fn output_scatter_columns_at(
+        mut self,
+        entity_path: impl Into<EntityPath>,
+        builder: impl FnOnce(ScatterColumnsBuilder) -> ScatterColumnsBuilder,
+    ) -> Self {
+        let output_builder =
+            ScatterColumnsBuilder::new(ast::TargetEntity::Explicit(entity_path.into()));
+        let output = builder(output_builder).build();
+        self.outputs.push(output);
+        self
+    }
+
+    /// Finalizes this builder and returns the corresponding lens.
+    pub fn build(self) -> ast::Lens {
+        ast::Lens {
+            input: self.input,
+            outputs: self.outputs,
+        }
+    }
+}
+
+// ==================== Output Builders ====================
+
+/// Builder for temporal outputs with 1:1 row mapping.
+///
+/// Each input row produces exactly one output row. Outputs inherit time columns
+/// from the input, plus any additional time columns specified.
+pub struct ColumnsBuilder {
+    target_entity: ast::TargetEntity,
+    components: Vec<ast::ComponentOutput>,
+    time_outputs: Vec<ast::TimeOutput>,
+}
+
+impl ColumnsBuilder {
+    fn new(target_entity: ast::TargetEntity) -> Self {
+        Self {
+            target_entity,
+            components: vec![],
+            time_outputs: vec![],
+        }
+    }
+
+    /// Adds a component output column.
+    ///
+    /// # Arguments
+    /// * `component_descr` - The descriptor for the output component
+    /// * `ops` - Sequence of operations to apply to transform the input column
+    pub fn component(
+        mut self,
+        component_descr: ComponentDescriptor,
+        ops: impl IntoIterator<Item = Op>,
+    ) -> Self {
+        self.components.push(ast::ComponentOutput {
+            component_descr,
+            ops: ops.into_iter().collect(),
+        });
+        self
+    }
+
+    /// Adds a time extraction.
+    ///
+    /// Extracts data from the input column to create a new time column for the output rows.
+    ///
+    /// # Arguments
+    /// * `timeline_name` - Name of the timeline to create
+    /// * `timeline_type` - Type of timeline (Sequence or Time)
+    /// * `ops` - Sequence of operations to extract time values (must produce [`arrow::array::Int64Array`])
+    pub fn time(
+        mut self,
+        timeline_name: impl Into<TimelineName>,
+        timeline_type: TimeType,
+        ops: impl IntoIterator<Item = Op>,
+    ) -> Self {
+        self.time_outputs.push(ast::TimeOutput {
+            timeline_name: timeline_name.into(),
+            timeline_type,
+            ops: ops.into_iter().collect(),
+        });
+        self
+    }
+
+    fn build(self) -> ast::LensKind {
+        if self.components.is_empty() {
+            re_log::warn_once!(
+                "Lens output created without any components. At least one component is required."
+            );
+        }
+
+        ast::LensKind::OneToOne {
+            target_entity: self.target_entity,
+            components: self.components,
+            timelines: self.time_outputs,
+        }
+    }
+}
+
+/// Builder for static outputs (timeless data).
+///
+/// Creates data that does not change over time. Static outputs have no associated time columns.
+pub struct StaticColumnsBuilder {
+    target_entity: ast::TargetEntity,
+    components: Vec<ast::ComponentOutput>,
+}
+
+impl StaticColumnsBuilder {
+    fn new(target_entity: ast::TargetEntity) -> Self {
+        Self {
+            target_entity,
+            components: vec![],
+        }
+    }
+
+    /// Adds a component output column.
+    ///
+    /// # Arguments
+    /// * `component_descr` - The descriptor for the output component
+    /// * `ops` - Sequence of operations to apply to transform the input column
+    pub fn component(
+        mut self,
+        component_descr: ComponentDescriptor,
+        ops: impl IntoIterator<Item = Op>,
+    ) -> Self {
+        self.components.push(ast::ComponentOutput {
+            component_descr,
+            ops: ops.into_iter().collect(),
+        });
+        self
+    }
+
+    fn build(self) -> ast::LensKind {
+        if self.components.is_empty() {
+            re_log::warn_once!(
+                "Lens output created without any components. At least one component is required."
+            );
+        }
+
+        ast::LensKind::Static {
+            target_entity: self.target_entity,
+            components: self.components,
+        }
+    }
+}
+
+/// Builder for temporal outputs with 1:N row mapping (scatter).
+///
+/// Each input row produces multiple output rows at the same timepoint. The timepoint
+/// is replicated/scattered across all output rows. This is useful for flattening lists
+/// or exploding batches while maintaining temporal alignment.
+pub struct ScatterColumnsBuilder {
+    target_entity: ast::TargetEntity,
+    components: Vec<ast::ComponentOutput>,
+    time_outputs: Vec<ast::TimeOutput>,
+}
+
+impl ScatterColumnsBuilder {
+    fn new(target_entity: ast::TargetEntity) -> Self {
+        Self {
+            target_entity,
+            components: vec![],
+            time_outputs: vec![],
+        }
+    }
+
+    /// Adds a component output column.
+    ///
+    /// # Arguments
+    /// * `component_descr` - The descriptor for the output component
+    /// * `ops` - Sequence of operations to apply to transform the input column
+    pub fn component(
+        mut self,
+        component_descr: ComponentDescriptor,
+        ops: impl IntoIterator<Item = Op>,
+    ) -> Self {
+        self.components.push(ast::ComponentOutput {
+            component_descr,
+            ops: ops.into_iter().collect(),
+        });
+        self
+    }
+
+    /// Adds a time extraction.
+    ///
+    /// Extracts data from the input column to create a new time column for the output rows.
+    ///
+    /// # Arguments
+    /// * `timeline_name` - Name of the timeline to create
+    /// * `timeline_type` - Type of timeline (Sequence or Time)
+    /// * `ops` - Sequence of operations to extract time values (must produce [`arrow::array::Int64Array`])
+    pub fn time(
+        mut self,
+        timeline_name: impl Into<TimelineName>,
+        timeline_type: TimeType,
+        ops: impl IntoIterator<Item = Op>,
+    ) -> Self {
+        self.time_outputs.push(ast::TimeOutput {
+            timeline_name: timeline_name.into(),
+            timeline_type,
+            ops: ops.into_iter().collect(),
+        });
+        self
+    }
+
+    fn build(self) -> ast::LensKind {
+        if self.components.is_empty() {
+            re_log::warn_once!(
+                "Lens scatter output created without any components. At least one component is required."
+            );
+        }
+
+        ast::LensKind::ToMany {
+            target_entity: self.target_entity,
+            components: self.components,
+            timelines: self.time_outputs,
+        }
+    }
+}

crates/top/re_sdk/src/lenses/builder.rs

@@ -5,14 +5,16 @@
 //! See [`lenses::Lens`] for more details and assumptions. One way to make use of lenses is
 //! by using the [`lenses::LensesSink`].
 
-pub(crate) mod ast;
+mod ast;
+mod builder;
 mod error;
 mod op;
 mod sink;
 
 pub use self::{
     // We should be careful not to expose to much implementation details here.
-    ast::{Lens, LensBuilder, Op},
+    ast::{Lens, Op},
+    builder::{ColumnsBuilder, LensBuilder, ScatterColumnsBuilder, StaticColumnsBuilder},
     error::Error,
     sink::LensesSink,
 };

crates/top/re_sdk/src/lenses/mod.rs

@@ -7,13 +7,10 @@
 use std::sync::Arc;
 
 use re_arrow_combinators::{Transform as _, map::MapList, reshape::GetField};
-use re_chunk::{
-    ArrowArray as _,
-    external::arrow::{
-        array::ListArray,
-        compute,
-        datatypes::{DataType, Field},
-    },
+use re_chunk::external::arrow::{
+    array::{Array as _, ListArray},
+    compute,
+    datatypes::{DataType, Field},
 };
 
 use super::Error;
@@ -50,3 +47,4 @@ impl Cast {
         ))
     }
 }
+