Codegen/IDL 4: definitions for a Points2D archetype (#2370)

Nothing but definitions!

And I say "a" `Points2D` rather than "the" `Points2D` because it's not
the point of this PR to nail down the perfect `Points2D` archetype
(yet); but rather get close enough and stress-test the whole system in
the process.

---

Codegen/IDL PR series:
- #2362
- #2363
- #2369
- #2370 
- #2374 
- #2375 
- #2410
- #2432

---------

Co-authored-by: Andreas Reich <[email protected]>

crates/re_types/definitions/arrow/attributes.fbs

@@ -6,12 +6,12 @@ namespace arrow;
 /// matter that only impacts (de)serialization.
 ///
 /// Only applies to unions.
-attribute "arrow.attr.sparse_union";
+attribute "attr.arrow.sparse_union";
 
 /// Marks a single-field object as transparent, affecting its Arrow datatype.
 ///
 /// This does _not_ affect the generated object structure in and of itself, it is a pure Arrow
 /// matter that only impacts (de)serialization.
 ///
 /// This is generally most useful for getting rid of extraneous `struct` layers.
-attribute "arrow.attr.transparent";
+attribute "attr.arrow.transparent";

crates/re_types/definitions/python/attributes.fbs

@@ -3,14 +3,14 @@ namespace python.attributes;
 /// Marks a field as transparent, meaning its type will be replaced by the underlying type.
 ///
 /// Only applies to fields whose type is an object with a single-field.
-attribute "python.attr.transparent";
+attribute "attr.python.transparent";
 
 /// Defines the type aliases for a component, e.g. the types that make up `ComponentLike`.
 ///
 /// Only applies to structs/unions that are components.
-attribute "python.attr.aliases";
+attribute "attr.python.aliases";
 
 /// Defines the array type aliases for a component, e.g. the types that make up `ComponentArrayLike`.
 ///
 /// Only applies to structs/unions that are components.
-attribute "python.attr.array_aliases";
+attribute "attr.python.array_aliases";

crates/re_types/definitions/rerun/archetypes/points2d.fbs

@@ -0,0 +1,63 @@
+include "fbs/attributes.fbs";
+
+include "rerun/datatypes.fbs";
+include "rerun/components.fbs";
+
+namespace rerun.archetypes;
+
+// ---
+
+// TODO(#2371): archetype IDL definitions must always be tables
+// TODO(#2372): archetype IDL definitions must refer to objects of kind component
+// TODO(#2373): `attr.rerun.component_required` implies `required`
+
+/// A 2D point cloud with positions and optional colors, radii, labels, etc.
+table Points2D (
+  "attr.rust.derive": "Debug, Clone, PartialEq",
+  order: 100
+) {
+  // --- Required ---
+
+  /// All the actual 2D points that make up the point cloud.
+  points: [rerun.components.Point2D] ("attr.rerun.component_required", required, order: 1000);
+
+  // --- Recommended ---
+
+  /// Optional radii for the points, effectively turning them into circles.
+  radii: [rerun.components.Radius] ("attr.rerun.component_recommended", order: 2000);
+
+  /// Optional colors for the points.
+  ///
+  /// \python The colors are interpreted as RGB or RGBA in sRGB gamma-space,
+  /// \python As either 0-1 floats or 0-255 integers, with separate alpha.
+  colors: [rerun.components.Color] ("attr.rerun.component_recommended", order: 2100);
+
+  // --- Optional ---
+
+  /// Optional text labels for the points.
+  labels: [rerun.components.Label] ("attr.rerun.component_optional", order: 3000);
+
+  /// An optional floating point value that specifies the 2D drawing order.
+  /// Objects with higher values are drawn on top of those with lower values.
+  ///
+  /// The default for 2D points is 30.0.
+  draw_order: rerun.components.DrawOrder ("attr.rerun.component_optional", order: 3100);
+
+  /// Optional class Ids for the points.
+  ///
+  /// The class ID provides colors and labels if not specified explicitly.
+  class_ids: [rerun.components.ClassId] ("attr.rerun.component_optional", order: 3200);
+
+  /// Optional keypoint IDs for the points, identifying them within a class.
+  ///
+  /// If keypoint IDs are passed in but no class IDs were specified, the class ID will
+  /// default to 0.
+  /// This is useful to identify points within a single classification (which is identified
+  /// with `class_id`).
+  /// E.g. the classification might be 'Person' and the keypoints refer to joints on a
+  /// detected skeleton.
+  keypoint_ids: [rerun.components.KeypointId] ("attr.rerun.component_optional", order: 3300);
+
+  /// Unique identifiers for each individual point in the batch.
+  instance_keys: [rerun.components.InstanceKey] ("attr.rerun.component_optional", order: 3400);
+}

crates/re_types/definitions/rerun/attributes.fbs

@@ -0,0 +1,19 @@
+namespace rerun.attributes;
+
+/// Marks a component as required, which is likely to impact the generated code in
+/// backend-specific ways.
+///
+/// Only applies to the fields of an archetype.
+attribute "attr.rerun.component_required";
+
+/// Marks a component as recommended, which is likely to impact the generated code in
+/// backend-specific ways.
+///
+/// Only applies to the fields of an archetype.
+attribute "attr.rerun.component_recommended";
+
+/// Marks a component as optional, which is likely to impact the generated code in
+/// backend-specific ways.
+///
+/// Only applies to the fields of an archetype.
+attribute "attr.rerun.component_optional";

crates/re_types/definitions/rerun/components.fbs

@@ -0,0 +1,8 @@
+include "./components/class_id.fbs";
+include "./components/color.fbs";
+include "./components/draw_order.fbs";
+include "./components/instance_key.fbs";
+include "./components/keypoint_id.fbs";
+include "./components/label.fbs";
+include "./components/point2d.fbs";
+include "./components/radius.fbs";

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

@@ -0,0 +1,23 @@
+include "arrow/attributes.fbs";
+include "python/attributes.fbs";
+include "rust/attributes.fbs";
+
+include "rerun/attributes.fbs";
+
+namespace rerun.components;
+
+// ---
+
+/// A 16-bit ID representing a type of semantic class.
+///
+/// \rs Used to look up a `crate::components::ClassDescription` within the `crate::components::AnnotationContext`.
+struct ClassId (
+  "attr.arrow.transparent",
+  "attr.python.aliases": "float",
+  "attr.python.array_aliases": "npt.NDArray[np.uint8], npt.NDArray[np.uint16], npt.NDArray[np.uint32]",
+  "attr.rust.derive": "Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash",
+  "attr.rust.tuple_struct",
+  order: 100
+) {
+  id: ushort;
+}

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

@@ -0,0 +1,23 @@
+include "arrow/attributes.fbs";
+include "python/attributes.fbs";
+include "rust/attributes.fbs";
+
+include "rerun/attributes.fbs";
+include "rerun/datatypes.fbs";
+
+namespace rerun.components;
+
+// ---
+
+/// An RGBA color tuple with unmultiplied/separate alpha, in sRGB gamma space with linear alpha.
+struct Color (
+  "attr.arrow.transparent",
+  "attr.python.aliases": "Sequence[int], Sequence[float], npt.NDArray[np.uint8], npt.NDArray[np.float32], npt.NDArray[np.float64]",
+  "attr.python.array_aliases": "Sequence[int], Sequence[float], npt.NDArray[np.uint8], npt.NDArray[np.float32], npt.NDArray[np.float64]",
+  "attr.rust.derive": "Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, bytemuck::Pod, bytemuck::Zeroable",
+  "attr.rust.repr": "transparent",
+  "attr.rust.tuple_struct",
+  order: 100
+) {
+  rgba: uint;
+}

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

@@ -0,0 +1,29 @@
+include "arrow/attributes.fbs";
+include "python/attributes.fbs";
+include "rust/attributes.fbs";
+
+include "rerun/datatypes.fbs";
+include "rerun/attributes.fbs";
+
+namespace rerun.components;
+
+// ---
+
+/// Draw order used for the display order of 2D elements.
+///
+/// Higher values are drawn on top of lower values.
+/// An entity can have only a single draw order component.
+/// Within an entity draw order is governed by the order of the components.
+///
+/// Draw order for entities with the same draw order is generally undefined.
+struct DrawOrder (
+  "attr.arrow.transparent",
+  "attr.python.aliases": "float",
+  "attr.python.array_aliases": "npt.NDArray[np.float32]",
+  "attr.rust.derive": "Debug, Clone, Copy, PartialEq, PartialOrd",
+  "attr.rust.repr": "transparent",
+  "attr.rust.tuple_struct",
+  order: 100
+) {
+   value: float;
+}

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

@@ -0,0 +1,22 @@
+include "arrow/attributes.fbs";
+include "python/attributes.fbs";
+include "rust/attributes.fbs";
+
+include "rerun/datatypes.fbs";
+include "rerun/attributes.fbs";
+
+namespace rerun.components;
+
+// ---
+
+/// A unique numeric identifier for each individual instance within a batch.
+struct InstanceKey (
+  "attr.arrow.transparent",
+  "attr.python.aliases": "int",
+  "attr.python.array_aliases": "npt.NDArray[np.uint64]",
+  "attr.rust.tuple_struct",
+  "attr.rust.derive": "Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord",
+  order: 100
+) {
+  value: uint64;
+}

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

@@ -0,0 +1,30 @@
+include "arrow/attributes.fbs";
+include "python/attributes.fbs";
+include "rust/attributes.fbs";
+
+include "rerun/attributes.fbs";
+
+namespace rerun.components;
+
+// ---
+
+/// A 16-bit ID representing a type of semantic keypoint within a class.
+///
+/// \py `KeypointId`s are only meaningful within the context of a [`rerun.components.ClassDescription`][].
+/// \py
+/// \py Used to look up an [`rerun.components.AnnotationInfo`][] for a Keypoint within the
+/// \py [`rerun.components.AnnotationContext`].
+///
+/// \rs `KeypointId`s are only meaningful within the context of a `crate::components::ClassDescription`.
+/// \rs
+/// \rs Used to look up an `crate::components::AnnotationInfo` for a Keypoint within the `crate::components::AnnotationContext`.
+struct KeypointId (
+  "attr.arrow.transparent",
+  "attr.python.aliases": "float",
+  "attr.python.array_aliases": "npt.NDArray[np.uint8], npt.NDArray[np.uint16], npt.NDArray[np.uint32]",
+  "attr.rust.derive": "Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash",
+  "attr.rust.tuple_struct",
+  order: 200
+) {
+  id: ushort;
+}

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

@@ -0,0 +1,22 @@
+include "arrow/attributes.fbs";
+include "python/attributes.fbs";
+include "rust/attributes.fbs";
+
+include "rerun/datatypes.fbs";
+include "rerun/attributes.fbs";
+
+namespace rerun.components;
+
+// ---
+
+/// A String label component.
+table Label (
+  "attr.arrow.transparent",
+  "attr.python.aliases": "str",
+  "attr.rust.derive": "Debug, Clone, PartialEq, Eq, PartialOrd, Ord",
+  "attr.rust.repr": "transparent",
+  "attr.rust.tuple_struct",
+  order: 100
+) {
+  value: string (required, order: 100);
+}

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

@@ -0,0 +1,25 @@
+include "arrow/attributes.fbs";
+include "python/attributes.fbs";
+include "rust/attributes.fbs";
+
+include "rerun/datatypes.fbs";
+include "rerun/attributes.fbs";
+
+namespace rerun.components;
+
+// ---
+
+/// A point in 2D space.
+struct Point2D (
+  "attr.arrow.transparent",
+  "attr.python.aliases": "npt.NDArray[np.float32], Sequence[float], Tuple[float, float]",
+  "attr.python.array_aliases": "npt.NDArray[np.float32], Sequence[float]",
+  "attr.rust.tuple_struct",
+  "attr.rust.derive": "Debug, Default, Clone, Copy, PartialEq, PartialOrd",
+  order: 100
+) {
+  position: rerun.datatypes.Vec2D (
+    "attr.python.transparent",
+    order: 100
+  );
+}

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

@@ -0,0 +1,22 @@
+include "arrow/attributes.fbs";
+include "python/attributes.fbs";
+include "rust/attributes.fbs";
+
+include "rerun/datatypes.fbs";
+include "rerun/attributes.fbs";
+
+namespace rerun.components;
+
+// ---
+
+/// A Radius component.
+struct Radius (
+  "attr.arrow.transparent",
+  "attr.python.aliases": "float",
+  "attr.python.array_aliases": "npt.NDArray[np.float32]",
+  "attr.rust.tuple_struct",
+  "attr.rust.derive": "Debug, Clone, Copy, PartialEq, PartialOrd",
+  order: 100
+) {
+  value: float;
+}

crates/re_types/definitions/rerun/datatypes.fbs

@@ -0,0 +1,3 @@
+include "./datatypes/vec2d.fbs";
+
+namespace rerun.datatypes;

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

@@ -0,0 +1,17 @@
+include "arrow/attributes.fbs";
+include "fbs/attributes.fbs";
+include "rust/attributes.fbs";
+
+namespace rerun.datatypes;
+
+// ---
+
+/// A vector in 2D space.
+struct Vec2D (
+  "attr.arrow.transparent",
+  "attr.rust.derive": "Debug, Default, Clone, Copy, PartialEq, PartialOrd",
+  "attr.rust.tuple_struct",
+  order: 100
+) {
+  xy: [float: 2];
+}

crates/re_types/definitions/rust/attributes.fbs

@@ -3,13 +3,13 @@ namespace rust.attributes;
 /// Apply to a struct or table object to generate a tuple struct.
 ///
 /// The type definition of the target object must have exactly a single field.
-attribute "rust.attr.tuple_struct";
+attribute "attr.rust.tuple_struct";
 
 /// Apply to any object to generate a #derive clause.
 ///
 /// The value of the attribute will be trimmed out but otherwise left as-is.
-/// E.g. "rust.attr.derive": "Debug, Clone, Copy"`.
-attribute "rust.attr.derive";
+/// E.g. "attr.rust.derive": "Debug, Clone, Copy"`.
+attribute "attr.rust.derive";
 
 /// Apply to any object to generate a #repr clause with the specified value.
-attribute "rust.attr.repr";
+attribute "attr.rust.repr";

crates/re_types/source_hash.txt

@@ -1,4 +1,4 @@
 # This is a sha256 hash for all direct and indirect dependencies of this crate's build script.
 # It can be safely removed at anytime to force the build script to run again.
 # Check out build.rs to see how it's computed.
-dae77f291d1698807cd865265cbb77731bd1aedf07c0968a6b0ac67c18f94590
+95c13226f31d47e4639e155fc80ee6830579c50e38ee1d997b4bda4d23ba03b6