Document DisconnectedSpaces boolean (#3760)

…and default it to `True` in Python.

* Closes #3599

### 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 [demo.rerun.io](https://demo.rerun.io/pr/3760) (if
applicable)
* [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/3760)
- [Docs
preview](https://rerun.io/preview/cecd2521e2e1a3affba182ee448f107ce40942ab/docs)
<!--DOCS-PREVIEW-->
- [Examples
preview](https://rerun.io/preview/cecd2521e2e1a3affba182ee448f107ce40942ab/examples)
<!--EXAMPLES-PREVIEW-->
- [Recent benchmark results](https://ref.rerun.io/dev/bench/)
- [Wasm size tracking](https://ref.rerun.io/dev/sizes/)

---------

Co-authored-by: Jeremy Leibs <[email protected]>

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

@@ -19,5 +19,6 @@ struct DisconnectedSpace (
   "attr.python.array_aliases": "bool, npt.NDArray[np.bool_]",
   "attr.rust.derive": "Copy, PartialEq, Eq"
 ) {
+  /// Whether the entity path at which this is logged is disconnected from its parent.
   is_disconnected: bool (order: 100);
 }

docs/code-examples/disconnected_space.py

@@ -8,5 +8,5 @@
 rr.log("world/room2/point", rr.Points3D([[1, 1, 1]]))
 
 # ..but this one lives in a completely separate space!
-rr.log("world/wormhole", rr.DisconnectedSpace(True))
+rr.log("world/wormhole", rr.DisconnectedSpace())
 rr.log("world/wormhole/point", rr.Points3D([[2, 2, 2]]))

rerun_py/rerun_sdk/rerun/archetypes/disconnected_space_ext.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..components import DisconnectedSpaceLike
+
+
+class DisconnectedSpaceExt:
+    """Extension for [DisconnectedSpace][rerun.archetypes.DisconnectedSpace]."""
+
+    def __init__(
+        self: Any,
+        is_disconnected: DisconnectedSpaceLike = True,
+    ):
+        """
+        Disconnect an entity from its parent.
+
+        Parameters
+        ----------
+        is_disconnected:
+            Whether or not the entity should be disconnected from the rest of the scene.
+            Set to `True` to disconnect the entity from its parent.
+            Set to `False` to disable the effects of this archetype, (re-)connecting the entity to its parent again.
+        """
+
+        self.__attrs_init__(is_disconnected)

rerun_py/rerun_sdk/rerun/components/disconnected_space_ext.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 import pyarrow as pa
@@ -12,6 +12,22 @@
 class DisconnectedSpaceExt:
     """Extension for [DisconnectedSpace][rerun.components.DisconnectedSpace]."""
 
+    def __init__(
+        self: Any,
+        is_disconnected: bool = True,
+    ):
+        """
+        Disconnect an entity from its parent.
+
+        Parameters
+        ----------
+        is_disconnected:
+            Whether or not the entity should be disconnected from the rest of the scene.
+            Set to `True` to disconnect the entity from its parent.
+            Set to `False` to disable the effects of this component, (re-)connecting the entity to its parent again.
+        """
+        self.__attrs_init__(is_disconnected=is_disconnected)
+
     @staticmethod
     def native_to_pa_array_override(data: DisconnectedSpaceArrayLike, data_type: pa.DataType) -> pa.Array:
         array = np.asarray(data, dtype=np.bool_).flatten()

rerun_py/rerun_sdk/rerun/log_deprecated/transform.py

@@ -198,7 +198,7 @@ def log_disconnected_space(
 
     recording = RecordingStream.to_native(recording)
 
-    log(entity_path, DisconnectedSpace(True), timeless=timeless, recording=recording)
+    log(entity_path, DisconnectedSpace(), timeless=timeless, recording=recording)
 
 
 @deprecated(

rerun_py/tests/unit/test_disconnected_space.py

@@ -9,7 +9,7 @@ def test_disconnected_space() -> None:
         # DisconnectedSpaceLike: bool
         True,
         # DisconnectedSpaceLike: DisconnectedSpace
-        DisconnectedSpace(True),
+        DisconnectedSpace(),
     ]
 
     for disconnected_space in disconnected_spaces:

tests/python/roundtrips/disconnected_space/main.py

@@ -16,7 +16,7 @@ def main() -> None:
 
     rr.script_setup(args, "rerun_example_roundtrip_disconnected_space")
 
-    rr.log("disconnected_space", rr.DisconnectedSpace(True))
+    rr.log("disconnected_space", rr.DisconnectedSpace())
 
     rr.script_teardown(args)
 

tests/python/test_api/main.py

@@ -145,7 +145,7 @@ def transforms(experimental_api: bool) -> None:
     rr.log("transforms", rr.ViewCoordinates.RIGHT_HAND_Y_UP, timeless=True)
 
     # Log a disconnected space (this doesn't do anything here, but can be used to force a new space)
-    rr.log("transforms/disconnected", rr.DisconnectedSpace(True))
+    rr.log("transforms/disconnected", rr.DisconnectedSpace())
 
     # Log scale along the x axis only.
     rr.log("transforms/x_scaled", rr.Transform3D(scale=(3, 1, 1)))