New transform components: Translation3D & TransformMat3x3

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 # ⚠️ Breaking changes
 * `mesh_material: Material` has been renamed to `albedo_factor: AlbedoFactor` [#6841](https://github.com/rerun-io/rerun/pull/6841)
+* 3D transform APIs: Previously, the transform component was represented as one of several variants (an Arrow union, `enum` in Rust) depending on how the transform was expressed. Instead, there are now several components for translation/scale/rotation/matrices that can live side-by-side in the 3D transform archetype.
 * Python: `NV12/YUY2` are now logged with the new `ImageChromaDownsampled`
 * `ImageEncoded`:s `format` parameter has been replaced with `media_type` (MIME)
 

crates/store/re_types/definitions/rerun/archetypes/transform3d.fbs

@@ -8,21 +8,38 @@ namespace rerun.archetypes;
 
 /// A transform between two 3D spaces, i.e. a pose.
 ///
+/// All components are applied in the order they are listed here.
+/// E.g. if both a 4x4 matrix with a translation and a translation vector are present,
+/// the matrix is applied first, then the translation vector on top.
+///
+/// Each transform component can be listed multiple times, but transform tree propagation is only possible
+/// if there's only one instance for each transform component.
+/// TODO(#6831): write more about the exact interaction with the to be written `OutOfTreeTransform` component.
+///
 /// \example archetypes/transform3d_simple title="Variety of 3D transforms" image="https://static.rerun.io/transform3d_simple/141368b07360ce3fcb1553079258ae3f42bdb9ac/1200w.png"
 /// \example archetypes/transform3d_hierarchy title="Transform hierarchy" image="https://static.rerun.io/transform_hierarchy/cb7be7a5a31fcb2efc02ba38e434849248f87554/1200w.png"
+// TODO(#6831): provide example with out of tree transform.
 table Transform3D (
-  "attr.rust.derive": "PartialEq",
+  "attr.rust.derive": "Default, PartialEq",
   "attr.docs.category": "Spatial 3D",
   "attr.docs.view_types": "Spatial3DView, Spatial2DView: if logged above active projection"
 ) {
   /// The transform
-  transform: rerun.components.Transform3D ("attr.rerun.component_required", order: 1000);
+  // TODO(#6831): remove.
+  transform: rerun.components.Transform3D ("attr.rerun.component_optional", order: 1000);
+
+  /// 3x3 transformation matrices.
+  mat3x3: [rerun.components.TransformMat3x3] ("attr.rerun.component_optional", nullable, order: 1100);
+
+  /// Translation vectors.
+  translation: [rerun.components.Translation3D] ("attr.rerun.component_optional", nullable, order: 1200);
 
-  // --- Optional ---
+  // --- visual representation
 
   /// Visual length of the 3 axes.
   ///
   /// The length is interpreted in the local coordinate system of the transform.
   /// If the transform is scaled, the axes will be scaled accordingly.
+  // TODO(#6831): Should be an array as well.
   axis_length: rerun.components.AxisLength ("attr.rerun.component_optional", nullable, order: 2000);
 }

crates/store/re_types/definitions/rerun/components.fbs

@@ -39,7 +39,9 @@ include "./components/tensor_dimension_selection.fbs";
 include "./components/texcoord2d.fbs";
 include "./components/text_log_level.fbs";
 include "./components/text.fbs";
+include "./components/transform_mat3x3.fbs";
 include "./components/transform3d.fbs";
+include "./components/translation3d.fbs";
 include "./components/triangle_indices.fbs";
 include "./components/vector2d.fbs";
 include "./components/vector3d.fbs";

crates/store/re_types/definitions/rerun/components/transform_mat3x3.fbs

@@ -0,0 +1,45 @@
+namespace rerun.components;
+
+/// A 3x3 transformation matrix Matrix.
+///
+/// 3x3 matrixes are able to represent any affine transformation in 3D space,
+/// i.e. rotation, scaling, shearing, reflection etc.
+///
+/// Matrices in Rerun are stored as flat list of coefficients in column-major order:
+/// ```text
+///             column 0       column 1       column 2
+///        -------------------------------------------------
+/// row 0 | flat_columns[0] flat_columns[3] flat_columns[6]
+/// row 1 | flat_columns[1] flat_columns[4] flat_columns[7]
+/// row 2 | flat_columns[2] flat_columns[5] flat_columns[8]
+/// ```
+///
+/// \py However, construction is done from a list of rows, which follows NumPy's convention:
+/// \py ```python
+/// \py np.testing.assert_array_equal(
+/// \py     rr.components.TransformMat3x3([1, 2, 3, 4, 5, 6, 7, 8, 9]).flat_columns, np.array([1, 4, 7, 2, 5, 8, 3, 6, 9], dtype=np.float32)
+/// \py )
+/// \py np.testing.assert_array_equal(
+/// \py     rr.components.TransformMat3x3([[1, 2, 3], [4, 5, 6], [7, 8, 9]]).flat_columns,
+/// \py     np.array([1, 4, 7, 2, 5, 8, 3, 6, 9], dtype=np.float32),
+/// \py )
+/// \py ```
+/// \py If you want to construct a matrix from a list of columns instead, use the named `columns` parameter:
+/// \py ```python
+/// \py np.testing.assert_array_equal(
+/// \py     rr.components.TransformMat3x3(columns=[1, 2, 3, 4, 5, 6, 7, 8, 9]).flat_columns,
+/// \py     np.array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=np.float32),
+/// \py )
+/// \py np.testing.assert_array_equal(
+/// \py     rr.components.TransformMat3x3(columns=[[1, 2, 3], [4, 5, 6], [7, 8, 9]]).flat_columns,
+/// \py     np.array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=np.float32),
+/// \py )
+/// \py ```
+struct TransformMat3x3 (
+  "attr.docs.unreleased",
+  "attr.rust.derive": "Default, Copy, PartialEq, bytemuck::Pod, bytemuck::Zeroable",
+  "attr.rust.repr": "transparent"
+) {
+  matrix: rerun.datatypes.Mat3x3 (order: 100);
+}
+

crates/store/re_types/definitions/rerun/components/translation3d.fbs

@@ -0,0 +1,10 @@
+namespace rerun.components;
+
+/// A translation vector in 3D space.
+struct Translation3D (
+  "attr.docs.unreleased",
+  "attr.rust.derive": "Default, Copy, PartialEq, bytemuck::Pod, bytemuck::Zeroable",
+  "attr.rust.repr": "transparent"
+) {
+  vector: rerun.datatypes.Vec3D (order: 100);
+}

crates/store/re_types/definitions/rerun/datatypes.fbs

@@ -25,7 +25,6 @@ include "./datatypes/tensor_dimension_selection.fbs";
 include "./datatypes/tensor_dimension.fbs";
 include "./datatypes/time_int.fbs";
 include "./datatypes/transform3d.fbs";
-include "./datatypes/translation_and_mat3x3.fbs";
 include "./datatypes/translation_rotation_scale3d.fbs";
 include "./datatypes/uint32.fbs";
 include "./datatypes/uint64.fbs";

crates/store/re_types/definitions/rerun/datatypes/mat3x3.fbs

@@ -43,7 +43,8 @@ namespace rerun.datatypes;
 struct Mat3x3 (
   "attr.arrow.transparent",
   "attr.python.aliases": "npt.ArrayLike",
-  "attr.rust.derive": "Copy, PartialEq, PartialOrd",
+  "attr.rust.derive": "Copy, PartialEq, PartialOrd, bytemuck::Pod, bytemuck::Zeroable",
+  "attr.rust.repr": "transparent",
   "attr.rust.tuple_struct"
 ) {
   /// Flat list of matrix coefficients in column-major order.

crates/store/re_types/definitions/rerun/datatypes/transform3d.fbs

@@ -12,9 +12,6 @@ namespace rerun.datatypes;
 union Transform3D (
   "attr.rust.derive": "Copy, PartialEq"
 ) {
-  /// Translation plus a 3x3 matrix for scale, rotation, skew, etc.
-  TranslationAndMat3x3: TranslationAndMat3x3,
-
   /// Translation, rotation and scale, decomposed.
   TranslationRotationScale: TranslationRotationScale3D,