anywidget-vector 0.1.0__tar.gz

anywidget_vector-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.cl*/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+venv/
+ENV/
+.env
+*.log
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.ty/
+node_modules/

anywidget_vector-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

anywidget_vector-0.1.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: anywidget-vector
+Version: 0.1.0
+Summary: Interactive vector visualization for Python notebooks using anywidget
+Project-URL: Homepage, https://grafeo.dev/
+Project-URL: Repository, https://github.com/GrafeoDB/anywidget-vector
+Author-email: "S.T. Grond" <widget@grafeo.dev>
+License: Apache-2.0
+Keywords: anywidget,jupyter,marimo,vector,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.12
+Requires-Dist: anywidget>=0.9.21
+Provides-Extra: all
+Requires-Dist: chromadb>=0.4; extra == 'all'
+Requires-Dist: numpy>=1.24; extra == 'all'
+Requires-Dist: pandas>=2.0; extra == 'all'
+Requires-Dist: qdrant-client>=1.0; extra == 'all'
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.4; extra == 'chroma'
+Provides-Extra: dev
+Requires-Dist: marimo>=0.19.7; extra == 'dev'
+Requires-Dist: prek>=0.3.1; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.14.14; extra == 'dev'
+Requires-Dist: ty>=0.0.14; extra == 'dev'
+Provides-Extra: lancedb
+Requires-Dist: lancedb>=0.1; extra == 'lancedb'
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.24; extra == 'numpy'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Provides-Extra: pinecone
+Requires-Dist: pinecone-client>=3.0; extra == 'pinecone'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.0; extra == 'qdrant'
+Provides-Extra: weaviate
+Requires-Dist: weaviate-client>=4.0; extra == 'weaviate'
+Description-Content-Type: text/markdown
+
+# anywidget-vector
+
+Interactive 3D vector visualization for Python notebooks.
+
+Works with Marimo, Jupyter, VS Code, Colab, anywhere [anywidget](https://anywidget.dev/) runs.
+
+## Features
+
+- **Universal** — One widget, every notebook environment
+- **6D Visualization** — X, Y, Z position + Color, Shape, Size encoding
+- **Backend-agnostic** — NumPy, pandas, Qdrant, Chroma, or raw dicts
+- **Interactive** — Orbit, pan, zoom, click, hover, select
+- **Customizable** — Color scales, shapes, sizes, themes
+- **Performant** — Instanced rendering for large point clouds
+
+## Installation
+
+```bash
+uv add anywidget-vector
+```
+
+## Quick Start
+
+```python
+from anywidget_vector import VectorSpace
+
+widget = VectorSpace(points=[
+    {"id": "a", "x": 0.5, "y": 0.3, "z": 0.8, "label": "Point A", "cluster": 0},
+    {"id": "b", "x": -0.2, "y": 0.7, "z": 0.1, "label": "Point B", "cluster": 1},
+    {"id": "c", "x": 0.1, "y": -0.4, "z": 0.6, "label": "Point C", "cluster": 0},
+])
+
+widget
+```
+
+## Data Sources
+
+### Dictionary
+
+```python
+from anywidget_vector import VectorSpace
+
+widget = VectorSpace.from_dict({
+    "points": [
+        {"id": "a", "x": 0, "y": 0, "z": 0},
+        {"id": "b", "x": 1, "y": 1, "z": 1},
+    ]
+})
+```
+
+### NumPy Arrays
+
+```python
+import numpy as np
+from anywidget_vector import VectorSpace
+
+positions = np.random.randn(100, 3)
+widget = VectorSpace.from_numpy(positions)
+```
+
+### pandas DataFrame
+
+```python
+import pandas as pd
+from anywidget_vector import VectorSpace
+
+df = pd.DataFrame({
+    "x": [0.1, 0.5, 0.9],
+    "y": [0.2, 0.6, 0.3],
+    "z": [0.3, 0.1, 0.7],
+    "cluster": ["A", "B", "A"],
+    "size": [0.5, 1.0, 0.8],
+})
+
+widget = VectorSpace.from_dataframe(
+    df,
+    color_col="cluster",
+    size_col="size",
+)
+```
+
+### UMAP / t-SNE / PCA
+
+```python
+import umap
+from anywidget_vector import VectorSpace
+
+# Reduce high-dimensional data to 3D
+embedding = umap.UMAP(n_components=3).fit_transform(high_dim_data)
+widget = VectorSpace.from_umap(embedding, labels=labels)
+```
+
+### Qdrant
+
+```python
+from qdrant_client import QdrantClient
+from anywidget_vector import VectorSpace
+
+client = QdrantClient("localhost", port=6333)
+widget = VectorSpace.from_qdrant(client, "my_collection", limit=5000)
+```
+
+### ChromaDB
+
+```python
+import chromadb
+from anywidget_vector import VectorSpace
+
+client = chromadb.Client()
+collection = client.get_collection("embeddings")
+widget = VectorSpace.from_chroma(collection)
+```
+
+## Visual Encoding
+
+### 6 Dimensions
+
+| Dimension | Visual Channel | Example |
+|-----------|---------------|---------|
+| X | Horizontal position | `x` coordinate |
+| Y | Vertical position | `y` coordinate |
+| Z | Depth position | `z` coordinate |
+| Color | Hue/gradient | Cluster, score |
+| Shape | Geometry | Category, type |
+| Size | Scale | Importance, count |
+
+### Color Scales
+
+```python
+widget = VectorSpace(
+    points=data,
+    color_field="score",           # Field to map
+    color_scale="viridis",         # Scale: viridis, plasma, inferno, magma, cividis, turbo
+    color_domain=[0, 100],         # Optional: explicit range
+)
+```
+
+### Shapes
+
+```python
+widget = VectorSpace(
+    points=data,
+    shape_field="category",
+    shape_map={
+        "type_a": "sphere",        # Available: sphere, cube, cone,
+        "type_b": "cube",          #            tetrahedron, octahedron, cylinder
+        "type_c": "cone",
+    }
+)
+```
+
+### Size
+
+```python
+widget = VectorSpace(
+    points=data,
+    size_field="importance",
+    size_range=[0.02, 0.15],       # Min/max point size
+)
+```
+
+## Interactivity
+
+### Events
+
+```python
+widget = VectorSpace(points=data)
+
+@widget.on_click
+def handle_click(point_id, point_data):
+    print(f"Clicked: {point_id}")
+    print(f"Data: {point_data}")
+
+@widget.on_hover
+def handle_hover(point_id, point_data):
+    if point_id:
+        print(f"Hovering: {point_id}")
+
+@widget.on_selection
+def handle_selection(point_ids, points_data):
+    print(f"Selected {len(point_ids)} points")
+```
+
+### Selection
+
+```python
+widget.selected_points          # Get current selection
+widget.select(["a", "b"])       # Select points
+widget.clear_selection()        # Clear
+```
+
+### Camera
+
+```python
+widget.camera_position          # Get position [x, y, z]
+widget.camera_target            # Get target [x, y, z]
+widget.reset_camera()           # Reset to default
+widget.focus_on(["a", "b"])     # Focus on specific points
+```
+
+## Options
+
+```python
+widget = VectorSpace(
+    points=data,
+    width=1000,
+    height=700,
+    background="#1a1a2e",         # Dark theme default
+    show_axes=True,
+    show_grid=True,
+    axis_labels={"x": "PC1", "y": "PC2", "z": "PC3"},
+    show_tooltip=True,
+    tooltip_fields=["label", "x", "y", "z", "cluster"],
+    selection_mode="click",       # "click" or "multi"
+    use_instancing=True,          # Performance: instanced rendering
+)
+```
+
+## Export
+
+```python
+widget.to_json()                # Export points as JSON string
+```
+
+## Environment Support
+
+| Environment | Supported |
+|-------------|-----------|
+| Marimo | ✅ |
+| JupyterLab | ✅ |
+| Jupyter Notebook | ✅ |
+| VS Code | ✅ |
+| Google Colab | ✅ |
+| Databricks | ✅ |
+
+## Related
+
+- [anywidget](https://anywidget.dev/) — Custom Jupyter widgets made easy
+- [anywidget-graph](https://github.com/GrafeoDB/anywidget-graph) — Graph visualization widget
+- [Three.js](https://threejs.org/) — 3D JavaScript library
+
+## License
+
+Apache-2.0

anywidget_vector-0.1.0/README.md

@@ -0,0 +1,244 @@
+# anywidget-vector
+
+Interactive 3D vector visualization for Python notebooks.
+
+Works with Marimo, Jupyter, VS Code, Colab, anywhere [anywidget](https://anywidget.dev/) runs.
+
+## Features
+
+- **Universal** — One widget, every notebook environment
+- **6D Visualization** — X, Y, Z position + Color, Shape, Size encoding
+- **Backend-agnostic** — NumPy, pandas, Qdrant, Chroma, or raw dicts
+- **Interactive** — Orbit, pan, zoom, click, hover, select
+- **Customizable** — Color scales, shapes, sizes, themes
+- **Performant** — Instanced rendering for large point clouds
+
+## Installation
+
+```bash
+uv add anywidget-vector
+```
+
+## Quick Start
+
+```python
+from anywidget_vector import VectorSpace
+
+widget = VectorSpace(points=[
+    {"id": "a", "x": 0.5, "y": 0.3, "z": 0.8, "label": "Point A", "cluster": 0},
+    {"id": "b", "x": -0.2, "y": 0.7, "z": 0.1, "label": "Point B", "cluster": 1},
+    {"id": "c", "x": 0.1, "y": -0.4, "z": 0.6, "label": "Point C", "cluster": 0},
+])
+
+widget
+```
+
+## Data Sources
+
+### Dictionary
+
+```python
+from anywidget_vector import VectorSpace
+
+widget = VectorSpace.from_dict({
+    "points": [
+        {"id": "a", "x": 0, "y": 0, "z": 0},
+        {"id": "b", "x": 1, "y": 1, "z": 1},
+    ]
+})
+```
+
+### NumPy Arrays
+
+```python
+import numpy as np
+from anywidget_vector import VectorSpace
+
+positions = np.random.randn(100, 3)
+widget = VectorSpace.from_numpy(positions)
+```
+
+### pandas DataFrame
+
+```python
+import pandas as pd
+from anywidget_vector import VectorSpace
+
+df = pd.DataFrame({
+    "x": [0.1, 0.5, 0.9],
+    "y": [0.2, 0.6, 0.3],
+    "z": [0.3, 0.1, 0.7],
+    "cluster": ["A", "B", "A"],
+    "size": [0.5, 1.0, 0.8],
+})
+
+widget = VectorSpace.from_dataframe(
+    df,
+    color_col="cluster",
+    size_col="size",
+)
+```
+
+### UMAP / t-SNE / PCA
+
+```python
+import umap
+from anywidget_vector import VectorSpace
+
+# Reduce high-dimensional data to 3D
+embedding = umap.UMAP(n_components=3).fit_transform(high_dim_data)
+widget = VectorSpace.from_umap(embedding, labels=labels)
+```
+
+### Qdrant
+
+```python
+from qdrant_client import QdrantClient
+from anywidget_vector import VectorSpace
+
+client = QdrantClient("localhost", port=6333)
+widget = VectorSpace.from_qdrant(client, "my_collection", limit=5000)
+```
+
+### ChromaDB
+
+```python
+import chromadb
+from anywidget_vector import VectorSpace
+
+client = chromadb.Client()
+collection = client.get_collection("embeddings")
+widget = VectorSpace.from_chroma(collection)
+```
+
+## Visual Encoding
+
+### 6 Dimensions
+
+| Dimension | Visual Channel | Example |
+|-----------|---------------|---------|
+| X | Horizontal position | `x` coordinate |
+| Y | Vertical position | `y` coordinate |
+| Z | Depth position | `z` coordinate |
+| Color | Hue/gradient | Cluster, score |
+| Shape | Geometry | Category, type |
+| Size | Scale | Importance, count |
+
+### Color Scales
+
+```python
+widget = VectorSpace(
+    points=data,
+    color_field="score",           # Field to map
+    color_scale="viridis",         # Scale: viridis, plasma, inferno, magma, cividis, turbo
+    color_domain=[0, 100],         # Optional: explicit range
+)
+```
+
+### Shapes
+
+```python
+widget = VectorSpace(
+    points=data,
+    shape_field="category",
+    shape_map={
+        "type_a": "sphere",        # Available: sphere, cube, cone,
+        "type_b": "cube",          #            tetrahedron, octahedron, cylinder
+        "type_c": "cone",
+    }
+)
+```
+
+### Size
+
+```python
+widget = VectorSpace(
+    points=data,
+    size_field="importance",
+    size_range=[0.02, 0.15],       # Min/max point size
+)
+```
+
+## Interactivity
+
+### Events
+
+```python
+widget = VectorSpace(points=data)
+
+@widget.on_click
+def handle_click(point_id, point_data):
+    print(f"Clicked: {point_id}")
+    print(f"Data: {point_data}")
+
+@widget.on_hover
+def handle_hover(point_id, point_data):
+    if point_id:
+        print(f"Hovering: {point_id}")
+
+@widget.on_selection
+def handle_selection(point_ids, points_data):
+    print(f"Selected {len(point_ids)} points")
+```
+
+### Selection
+
+```python
+widget.selected_points          # Get current selection
+widget.select(["a", "b"])       # Select points
+widget.clear_selection()        # Clear
+```
+
+### Camera
+
+```python
+widget.camera_position          # Get position [x, y, z]
+widget.camera_target            # Get target [x, y, z]
+widget.reset_camera()           # Reset to default
+widget.focus_on(["a", "b"])     # Focus on specific points
+```
+
+## Options
+
+```python
+widget = VectorSpace(
+    points=data,
+    width=1000,
+    height=700,
+    background="#1a1a2e",         # Dark theme default
+    show_axes=True,
+    show_grid=True,
+    axis_labels={"x": "PC1", "y": "PC2", "z": "PC3"},
+    show_tooltip=True,
+    tooltip_fields=["label", "x", "y", "z", "cluster"],
+    selection_mode="click",       # "click" or "multi"
+    use_instancing=True,          # Performance: instanced rendering
+)
+```
+
+## Export
+
+```python
+widget.to_json()                # Export points as JSON string
+```
+
+## Environment Support
+
+| Environment | Supported |
+|-------------|-----------|
+| Marimo | ✅ |
+| JupyterLab | ✅ |
+| Jupyter Notebook | ✅ |
+| VS Code | ✅ |
+| Google Colab | ✅ |
+| Databricks | ✅ |
+
+## Related
+
+- [anywidget](https://anywidget.dev/) — Custom Jupyter widgets made easy
+- [anywidget-graph](https://github.com/GrafeoDB/anywidget-graph) — Graph visualization widget
+- [Three.js](https://threejs.org/) — 3D JavaScript library
+
+## License
+
+Apache-2.0

anywidget_vector-0.1.0/pyproject.toml

@@ -0,0 +1,101 @@
+[project]
+name = "anywidget-vector"
+version = "0.1.0"
+description = "Interactive vector visualization for Python notebooks using anywidget"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.12"
+authors = [{ name = "S.T. Grond", email = "widget@grafeo.dev" }]
+keywords = ["anywidget", "vector", "visualization", "jupyter", "marimo"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Jupyter",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+dependencies = [
+    "anywidget>=0.9.21",
+]
+
+[project.optional-dependencies]
+dev = [
+    "prek>=0.3.1",
+    "pytest>=9.0.2",
+    "ruff>=0.14.14",
+    "ty>=0.0.14",
+    "marimo>=0.19.7",
+]
+pandas = ["pandas>=2.0"]
+numpy = ["numpy>=1.24"]
+qdrant = ["qdrant-client>=1.0"]
+chroma = ["chromadb>=0.4"]
+pinecone = ["pinecone-client>=3.0"]
+weaviate = ["weaviate-client>=4.0"]
+lancedb = ["lancedb>=0.1"]
+all = [
+    "pandas>=2.0",
+    "numpy>=1.24",
+    "qdrant-client>=1.0",
+    "chromadb>=0.4",
+]
+
+[project.urls]
+Homepage = "https://grafeo.dev/"
+Repository = "https://github.com/GrafeoDB/anywidget-vector"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anywidget_vector"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "FA",
+    "Q",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/anywidget_vector/widget.py" = ["E501"]  # Long lines in embedded JS
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "double"
+docstring-quotes = "double"
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-v"
+
+[tool.prek]
+repos = [
+    { repo = "ruff", hooks = [
+        { id = "ruff-check", args = ["--fix", "--exit-non-zero-on-fix"] },
+        { id = "ruff-format" },
+    ]},
+]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=9.0.2",
+    "ruff>=0.14.14",
+]

anywidget_vector-0.1.0/src/anywidget_vector/__init__.py

@@ -0,0 +1,6 @@
+"""Interactive 3D vector visualization for Python notebooks."""
+
+from anywidget_vector.widget import VectorSpace
+
+__all__ = ["VectorSpace"]
+__version__ = "0.1.0"