scatter3d-anywidget 0.1.2__tar.gz

scatter3d_anywidget-0.1.2/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.3
+Name: scatter3d-anywidget
+Version: 0.1.2
+Summary: 3D scatter widget with lasso selection
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: anywidget>=0.9.21
+Requires-Dist: narwhals>=2.14.0
+Requires-Dist: numpy>=2.3.5
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/JoseBlanca/any_scatter3d
+Project-URL: Issues, https://github.com/JoseBlanca/any_scatter3d/issues
+Project-URL: Repository, https://github.com/JoseBlanca/any_scatter3d
+Description-Content-Type: text/markdown
+
+# scatter3d-anywidget
+
+**Interactive 3D scatter plots for Python notebooks, with lasso-based selection and categorical annotation.**
+
+`scatter3d-anywidget` provides a high-performance, WebGL-based 3D scatter plot widget built on top of **[anywidget](https://anywidget.dev/)**.
+It is designed for exploratory data analysis workflows where users need to **interactively select, assign, and modify categories** on point clouds.
+
+![scatter3d widget example](scatter_widget_example.png)
+
+## Features
+
+* **3D scatter visualization** (WebGL / Three.js) (up to tens of thousands of points)
+* **Lasso selection** with *add* and *remove* operations
+* **Categorical annotation** backed by pandas or Polars Series thanks to [narwhals](https://narwhals-dev.github.io/narwhals/)
+* **Bidirectional sync** between Python state and frontend
+* Designed for **anywidget**, works well with **marimo** and Jupyter
+
+## Project status
+
+⚠️ **Alpha status**, this is alpha software that we are using in our research.
+
+This project is under active development.  
+APIs, traitlets, and frontend behavior may change without notice.
+
+Contributions and feedback are welcome.
+
+
+## Installation
+
+```bash
+pip install scatter3d-anywidget
+```
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+
+## Requirements
+
+- Python ≥ 3.13
+- Jupyter or marimo
+- WebGL-capable browser
+
+## Basic usage
+
+Below is a minimal example showing how to:
+
+* Create a 3D scatter plot
+* Attach a categorical variable
+* Modify category labels programmatically
+* Inspect lasso selections from Python
+
+```python
+import random
+import numpy as np
+import pandas as pd
+import marimo
+
+from scatter3d import Scatter3dWidget, Category, LabelListErrorResponse
+
+num_points = 10_000
+
+# Generate random 3D points
+points = np.random.randn(num_points, 3)
+
+# Create a categorical variable
+species_list = ["species1", "species2", "species3"]
+species = random.choices(species_list, k=num_points)
+species = Category(pd.Series(species, name="species"))
+
+# Create the widget
+w = Scatter3dWidget(xyz=points, category=species)
+w.point_size = 0.15
+
+# Modify allowed labels
+species.set_label_list(
+    ["species1"],
+    on_missing_labels=LabelListErrorResponse.SET_MISSING,
+)
+
+species.set_label_list(["species1", "species4"])
+
+# Display in marimo / Jupyter
+ui = marimo.ui.anywidget(w)
+ui
+```
+
+After interacting with the plot (e.g. lasso selection), you can inspect results from Python:
+
+```python
+# Result of the last lasso operation
+ui.lasso_result_t
+
+# Category statistics
+print(species.values.value_counts())
+print(species.num_unassigned)
+```
+
+## Interactive operation
+
+The widget is fully interactive and designed for exploratory annotation workflows. Users can rotate, pan, and zoom the 3D point cloud directly with the mouse. A lasso tool allows drawing a free-form polygon in screen space to select subsets of points. Once a lasso selection is completed, the selection can be applied to the active category using add or remove operations, updating both the visual state and the underlying Python Category object. All interactions are bidirectionally synchronized: changes made via the UI are immediately reflected in Python, and programmatic updates from Python are propagated back to the frontend. This enables tight interactive loops where visual inspection, manual selection, and scripted analysis coexist seamlessly.
+
+## Concepts
+
+### `Scatter3dWidget`
+
+The main widget. It owns the point cloud, rendering state, and interaction logic.
+
+### `Category`
+
+A wrapper around a categorical vector (pandas or Polars Series) that:
+
+* Encodes categories efficiently
+* Tracks unassigned values
+* `Category` objects are **stateful**: updating them updates the widget, and vice versa.
+
+### Lasso interaction
+
+The lasso tool allows:
+
+* Selecting points in screen space
+* Adding or removing points from a category
+* Reading back selection results in Python
+
+## License
+
+MIT

scatter3d_anywidget-0.1.2/README.md

@@ -0,0 +1,125 @@
+# scatter3d-anywidget
+
+**Interactive 3D scatter plots for Python notebooks, with lasso-based selection and categorical annotation.**
+
+`scatter3d-anywidget` provides a high-performance, WebGL-based 3D scatter plot widget built on top of **[anywidget](https://anywidget.dev/)**.
+It is designed for exploratory data analysis workflows where users need to **interactively select, assign, and modify categories** on point clouds.
+
+![scatter3d widget example](scatter_widget_example.png)
+
+## Features
+
+* **3D scatter visualization** (WebGL / Three.js) (up to tens of thousands of points)
+* **Lasso selection** with *add* and *remove* operations
+* **Categorical annotation** backed by pandas or Polars Series thanks to [narwhals](https://narwhals-dev.github.io/narwhals/)
+* **Bidirectional sync** between Python state and frontend
+* Designed for **anywidget**, works well with **marimo** and Jupyter
+
+## Project status
+
+⚠️ **Alpha status**, this is alpha software that we are using in our research.
+
+This project is under active development.  
+APIs, traitlets, and frontend behavior may change without notice.
+
+Contributions and feedback are welcome.
+
+
+## Installation
+
+```bash
+pip install scatter3d-anywidget
+```
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+
+## Requirements
+
+- Python ≥ 3.13
+- Jupyter or marimo
+- WebGL-capable browser
+
+## Basic usage
+
+Below is a minimal example showing how to:
+
+* Create a 3D scatter plot
+* Attach a categorical variable
+* Modify category labels programmatically
+* Inspect lasso selections from Python
+
+```python
+import random
+import numpy as np
+import pandas as pd
+import marimo
+
+from scatter3d import Scatter3dWidget, Category, LabelListErrorResponse
+
+num_points = 10_000
+
+# Generate random 3D points
+points = np.random.randn(num_points, 3)
+
+# Create a categorical variable
+species_list = ["species1", "species2", "species3"]
+species = random.choices(species_list, k=num_points)
+species = Category(pd.Series(species, name="species"))
+
+# Create the widget
+w = Scatter3dWidget(xyz=points, category=species)
+w.point_size = 0.15
+
+# Modify allowed labels
+species.set_label_list(
+    ["species1"],
+    on_missing_labels=LabelListErrorResponse.SET_MISSING,
+)
+
+species.set_label_list(["species1", "species4"])
+
+# Display in marimo / Jupyter
+ui = marimo.ui.anywidget(w)
+ui
+```
+
+After interacting with the plot (e.g. lasso selection), you can inspect results from Python:
+
+```python
+# Result of the last lasso operation
+ui.lasso_result_t
+
+# Category statistics
+print(species.values.value_counts())
+print(species.num_unassigned)
+```
+
+## Interactive operation
+
+The widget is fully interactive and designed for exploratory annotation workflows. Users can rotate, pan, and zoom the 3D point cloud directly with the mouse. A lasso tool allows drawing a free-form polygon in screen space to select subsets of points. Once a lasso selection is completed, the selection can be applied to the active category using add or remove operations, updating both the visual state and the underlying Python Category object. All interactions are bidirectionally synchronized: changes made via the UI are immediately reflected in Python, and programmatic updates from Python are propagated back to the frontend. This enables tight interactive loops where visual inspection, manual selection, and scripted analysis coexist seamlessly.
+
+## Concepts
+
+### `Scatter3dWidget`
+
+The main widget. It owns the point cloud, rendering state, and interaction logic.
+
+### `Category`
+
+A wrapper around a categorical vector (pandas or Polars Series) that:
+
+* Encodes categories efficiently
+* Tracks unassigned values
+* `Category` objects are **stateful**: updating them updates the widget, and vice versa.
+
+### Lasso interaction
+
+The lasso tool allows:
+
+* Selecting points in screen space
+* Adding or removing points from a category
+* Reading back selection results in Python
+
+## License
+
+MIT

scatter3d_anywidget-0.1.2/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "scatter3d-anywidget"
+version = "0.1.2"
+description = "3D scatter widget with lasso selection"
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "MIT" }
+dependencies = ["anywidget>=0.9.21", "narwhals>=2.14.0", "numpy>=2.3.5"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "scatter3d"
+
+[dependency-groups]
+dev = ["marimo>=0.18.4", "pandas>=2.3.3", "polars>=1.36.1", "pytest>=9.0.2"]
+
+[project.urls]
+Homepage = "https://github.com/JoseBlanca/any_scatter3d"
+Repository = "https://github.com/JoseBlanca/any_scatter3d"
+Issues = "https://github.com/JoseBlanca/any_scatter3d/issues"

scatter3d_anywidget-0.1.2/src/scatter3d/__init__.py

@@ -0,0 +1,3 @@
+from .scatter3d import Scatter3dWidget, Category, LabelListErrorResponse
+
+__all__ = ["Scatter3dWidget", "Category", "LabelListErrorResponse"]