scatter3d-anywidget 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

scatter3d/scatter3d.py

@@ -80,6 +80,7 @@ class Category:
         label_list=None,
         color_palette: dict[Any, tuple[float, float, float]] | None = None,
         missing_color: tuple[float, float, float] = MISSING_COLOR,
+        editable: bool = True,
     ):
         self._cb_id_gen = count(1)
         self._callbacks: dict[int, weakref.ReferenceType] = {}
@@ -102,6 +103,8 @@ class Category:
         _is_valid_color(missing_color)
         self._missing_color = missing_color
 
+        self._editable = bool(editable)
+
     def subscribe(self, cb: CategoryCallback) -> int:
         cb_id = next(self._cb_id_gen)
         try:
@@ -125,6 +128,10 @@ class Category:
         for cb_id in dead:
             self._callbacks.pop(cb_id, None)
 
+    @property
+    def editable(self) -> bool:
+        return self._editable
+
     @staticmethod
     def _get_unique_labels_in_values(values):
         return values.drop_nulls().unique().to_list()
@@ -495,6 +502,11 @@ class Scatter3dWidget(anywidget.AnyWidget):
         help="Desired widget height in CSS pixels. Frontend will clamp to notebook constraints.",
     ).tag(sync=True)
 
+    category_editable_t = traitlets.Bool(
+        default_value=True,
+        help="Whether the active category is editable (enables lasso UI).",
+    ).tag(sync=True)
+
     def __init__(
         self,
         xyz: numpy.ndarray,
@@ -507,6 +519,9 @@ class Scatter3dWidget(anywidget.AnyWidget):
         super().__init__()
         self._category_cb_id: int | None = None
 
+        # Guard to suppress trait observers during multi-traitlet sync bursts
+        self._syncing_category = False
+
         if category is not None and xyz.shape[0] != category.num_values:
             raise ValueError(
                 f"The number of points ({xyz.shape[0]}) should match "
@@ -628,13 +643,19 @@ class Scatter3dWidget(anywidget.AnyWidget):
 
     @traitlets.observe("labels_t")
     def _on_labels_t(self, change) -> None:
+        # During category sync we temporarily allow intermediate inconsistent states.
+        if getattr(self, "_syncing_category", False):
+            return
+
         if self.interaction_mode_t == "lasso":
             self._ensure_active_category_invariants()
         elif self.active_category_t is not None and self.active_category_t not in (
             change.get("new") or []
         ):
             # in rotate mode, invalid active is a real error
-            raise RuntimeError(...)
+            raise RuntimeError(
+                f"active_category_t={self.active_category_t!r} is not present in labels_t after labels update"
+            )
 
     @traitlets.observe("client_ready_t")
     def _on_client_ready_t(self, change) -> None:
@@ -730,6 +751,10 @@ class Scatter3dWidget(anywidget.AnyWidget):
             )
         return v
 
+    @property
+    def active_category(self):
+        return self.active_category_t
+
     @traitlets.observe("tooltip_request_t")
     def _on_tooltip_request(self, change) -> None:
         req = change["new"] or {}
@@ -839,34 +864,54 @@ class Scatter3dWidget(anywidget.AnyWidget):
         if self._category is None:
             raise RuntimeError("The category should be set")
 
-        cat = self._category
+        self._syncing_category = True
+        try:
+            cat = self._category
 
-        # labels_t must be JSON-friendly; enforce str
-        labels = [str(lbl) for lbl in cat.label_list]
-        self.labels_t = labels
+            # labels_t must be JSON-friendly; enforce str
+            labels = [str(lbl) for lbl in cat.label_list]
+            self.labels_t = labels
 
-        # coded values: uint16 bytes, length N
-        coded = cat.coded_values
-        if coded.shape[0] != self.num_points:
-            raise RuntimeError(
-                f"Category has {coded.shape[0]} values but xyz has {self.num_points} points"
-            )
-        self.coded_values_t = self._pack_u16_c(coded)
+            self.category_editable_t = cat.editable
 
-        # colors aligned with labels order
-        # Category stores palette keyed by original labels; we reconstruct in label_list order.
-        palette = cat.color_palette  # label -> (r,g,b)
-        self.colors_t = [list(map(float, palette[lbl])) for lbl in cat.label_list]
+            if not self.category_editable_t and self.interaction_mode_t == "lasso":
+                self.interaction_mode_t = "rotate"
+                if self.interactive_ready_t:
+                    self.send_state("interaction_mode_t")
 
-        # missing color
-        self.missing_color_t = list(map(float, cat.missing_color))
+            coded = cat.coded_values
+            if coded.shape[0] != self.num_points:
+                raise RuntimeError(
+                    f"Category has {coded.shape[0]} values but xyz has {self.num_points} points"
+                )
+            self.coded_values_t = self._pack_u16_c(coded)
 
-        if len(self.colors_t) != len(self.labels_t):
-            raise RuntimeError(
-                "Internal error: colors_t length must match labels_t length"
-            )
+            palette = cat.color_palette  # label -> (r,g,b)
+            self.colors_t = [list(map(float, palette[lbl])) for lbl in cat.label_list]
 
-        self._ensure_active_category_invariants()
+            self.missing_color_t = list(map(float, cat.missing_color))
+
+            if len(self.colors_t) != len(self.labels_t):
+                raise RuntimeError(
+                    "Internal error: colors_t length must match labels_t length"
+                )
+
+            # Now that labels/colors are consistent, enforce a stable policy for active category.
+            if self.interaction_mode_t == "rotate":
+                if (
+                    self.active_category_t is not None
+                    and self.active_category_t not in self.labels_t
+                ):
+                    # Professional + predictable: clear invalid selection on category switch.
+                    self.active_category_t = None
+                    if self.interactive_ready_t:
+                        self.send_state("active_category_t")
+            else:
+                # lasso mode keeps existing behavior: ensure a valid active label exists.
+                self._ensure_active_category_invariants()
+
+        finally:
+            self._syncing_category = False
 
     def _get_category(self):
         return self._category