Fill gaps in image encoding documentation, fix how python documents u…

…nion variants (rerun-io#4988)

### What

* Fixes rerun-io#4820

Turned out union documentation didn't look great so I improved this a
bit

![image](https://github.com/rerun-io/rerun/assets/1220815/29367f7d-c3b3-4757-8e8a-8ecc18ae9cea)


### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested the web demo (if applicable):
* Using newly built examples:
[app.rerun.io](https://app.rerun.io/pr/4988/index.html)
* Using examples from latest `main` build:
[app.rerun.io](https://app.rerun.io/pr/4988/index.html?manifest_url=https://app.rerun.io/version/main/examples_manifest.json)
* Using full set of examples from `nightly` build:
[app.rerun.io](https://app.rerun.io/pr/4988/index.html?manifest_url=https://app.rerun.io/version/nightly/examples_manifest.json)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG

- [PR Build Summary](https://build.rerun.io/pr/4988)
- [Docs
preview](https://rerun.io/preview/bc6f54745d7384b904466c2911ac2c93f42a3b53/docs)
<!--DOCS-PREVIEW-->
- [Examples
preview](https://rerun.io/preview/bc6f54745d7384b904466c2911ac2c93f42a3b53/examples)
<!--EXAMPLES-PREVIEW-->
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)

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

@@ -19,6 +19,7 @@ namespace rerun.archetypes;
 /// \cpp Since the underlying `rerun::datatypes::TensorData` uses `rerun::Collection` internally,
 /// \cpp data can be passed in without a copy from raw pointers or by reference from `std::vector`/`std::array`/c-arrays.
 /// \cpp If needed, this "borrow-behavior" can be extended by defining your own `rerun::CollectionAdapter`.
+/// \python For an easy way to pass in image formats or encoded images, see [`rerun.ImageEncoded`][].
 ///
 /// \example image_simple image="https://static.rerun.io/image_simple/06ba7f8582acc1ffb42a7fd0006fad7816f3e4e4/1200w.png"
 table Image (

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

@@ -9,7 +9,19 @@ namespace rerun.components;
 
 // ---
 
-/// A multi-dimensional `Tensor` with optionally named arguments.
+/// A multi-dimensional `Tensor` of data.
+///
+/// The number of dimensions and their respective lengths is specified by the `shape` field.
+/// The dimensions are ordered from outermost to innermost. For example, in the common case of
+/// a 2D RGB Image, the shape would be `[height, width, channel]`.
+///
+/// These dimensions are combined with an index to look up values from the `buffer` field,
+/// which stores a contiguous array of typed values.
+///
+/// Note that the buffer may be encoded in a compressed format such as `jpeg` or
+/// in a format with downsampled chroma, such as NV12 or YUY2.
+/// For file formats, the shape is used as a hint, for chroma downsampled format
+/// the shape has to be the shape of the decoded image.
 table TensorData (
   "attr.arrow.transparent",
   "attr.rust.derive": "PartialEq",

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

@@ -49,12 +49,15 @@ table F64Buffer(order: 100, transparent) {
   data: [double] (order: 100);
 }
 
+/// Raw bytes of a JPEG file.
 table JPEGBuffer(order: 100, transparent) {
   data: [ubyte] (order: 100);
 }
+
 table NV12Buffer(order: 100, transparent) {
   data: [ubyte] (order: 100);
 }
+
 table YUY2Buffer(order: 100, transparent) {
   data: [ubyte] (order: 100);
 }
@@ -66,18 +69,49 @@ table YUY2Buffer(order: 100, transparent) {
 union TensorBuffer (
   "attr.rust.derive_only": "Clone, PartialEq"
 ) {
+  /// 8bit unsigned integer.
   U8: U8Buffer (transparent, order:100),
+
+  /// 16bit unsigned integer.
   U16: U16Buffer (transparent, order:200),
+
+  /// 32bit unsigned integer.
   U32: U32Buffer (transparent, order:300),
+
+  /// 64bit unsigned integer.
   U64: U64Buffer (transparent, order:400),
+
+  /// 8bit signed integer.
   I8: I8Buffer (transparent, order:500),
+
+  /// 16bit signed integer.
   I16: I16Buffer (transparent, order:600),
+
+  /// 32bit signed integer.
   I32: I32Buffer (transparent, order:700),
+
+  /// 64bit signed integer.
   I64: I64Buffer (transparent, order:800),
+
+  /// 16bit IEEE-754 floating point, also known as `half`.
   F16: F16Buffer (transparent, order:900),
+
+  /// 32bit IEEE-754 floating point, also known as `float` or `single`.
   F32: F32Buffer (transparent, order:1000),
+
+  /// 64bit IEEE-754 floating point, also known as `double`.
   F64: F64Buffer (transparent, order:1200),
+
+  /// Raw bytes of a JPEG file.
   JPEG: JPEGBuffer (transparent, order:1300),
+
+  /// NV12 is a YUV 4:2:0 chroma downsamples format with 8 bits per channel.
+  ///
+  /// First comes entire image in Y, followed by interleaved lines ordered as U0, V0, U1, V1, etc.
   NV12: NV12Buffer (transparent, order:1400),
+
+  /// YUY2, also known as YUYV is a YUV 4:2:2 chrome downsampled format with 8 bits per channel.
+  ///
+  /// The order of the channels is Y0, U0, Y1, V0.
   YUY2: YUY2Buffer (transparent, order:1500),
 }

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

@@ -16,6 +16,11 @@ namespace rerun.datatypes;
 ///
 /// These dimensions are combined with an index to look up values from the `buffer` field,
 /// which stores a contiguous array of typed values.
+///
+/// Note that the buffer may be encoded in a compressed format such as `jpeg` or
+/// in a format with downsampled chroma, such as NV12 or YUY2.
+/// For file formats, the shape is used as a hint, for chroma downsampled format
+/// the shape has to be the shape of the decoded image.
 table TensorData (
   "attr.python.aliases": "npt.ArrayLike",
   "attr.python.array_aliases": "npt.ArrayLike",

crates/re_types_builder/src/codegen/python.rs

@@ -874,6 +874,8 @@ fn code_for_union(
             1,
             4,
         );
+
+        code.push_text(quote_union_kind_from_fields(fields), 0, 4);
     }
 
     code.push_unindented_text(quote_union_aliases_from_object(obj, field_types.iter()), 1);
@@ -1021,7 +1023,7 @@ fn quote_doc_lines(lines: Vec<String>) -> String {
 }
 
 fn quote_doc_from_fields(objects: &Objects, fields: &Vec<ObjectField>) -> String {
-    let mut lines = vec![];
+    let mut lines = vec!["Must be one of:".to_owned(), String::new()];
 
     for field in fields {
         let mut content = crate::codegen::get_documentation(&field.docs, &["py", "python"]);
@@ -1037,7 +1039,7 @@ fn quote_doc_from_fields(objects: &Objects, fields: &Vec<ObjectField>) -> String
             quote_examples(examples, &mut lines);
         }
         lines.push(format!(
-            "{} ({}):",
+            "* {} ({}):",
             field.name,
             quote_field_type_from_field(objects, field, false).0
         ));
@@ -1062,6 +1064,38 @@ fn quote_doc_from_fields(objects: &Objects, fields: &Vec<ObjectField>) -> String
     format!("\"\"\"\n{doc}\n\"\"\"\n\n")
 }
 
+fn quote_union_kind_from_fields(fields: &Vec<ObjectField>) -> String {
+    let mut lines = vec!["Possible values:".to_owned(), String::new()];
+
+    for field in fields {
+        let mut content = crate::codegen::get_documentation(&field.docs, &["py", "python"]);
+        for line in &mut content {
+            if line.starts_with(char::is_whitespace) {
+                line.remove(0);
+            }
+        }
+        lines.push(format!("* {:?}:", field.name));
+        lines.extend(content.into_iter().map(|line| format!("    {line}")));
+        lines.push(String::new());
+    }
+
+    if lines.is_empty() {
+        return String::new();
+    } else {
+        // remove last empty line
+        lines.pop();
+    }
+
+    // NOTE: Filter out docstrings within docstrings, it just gets crazy otherwise…
+    let doc = lines
+        .into_iter()
+        .filter(|line| !line.starts_with(r#"""""#))
+        .collect_vec()
+        .join("\n");
+
+    format!("\"\"\"\n{doc}\n\"\"\"\n\n")
+}
+
 /// Automatically implement `__array__` if the object is a single
 /// `npt.ArrayLike`/integer/floating-point field.
 ///

docs/cspell.json

@@ -181,6 +181,7 @@
     "docstring",
     "docstrings",
     "dont",
+    "downsampled",
     "downscaled",
     "downscaling",
     "drawables",