tangram-explore 0.3.0__tar.gz

tangram_explore-0.3.0/.gitignore

@@ -0,0 +1,173 @@
+packages/tangram_*/src/tangram_*/package.json
+
+# Configuration file
+tangram.toml
+
+dist-frontend
+**/node_modules
+
+### Archive ###
+archive/
+*.ipynb
+.git-old
+.vscode/
+.idea/
+
+### Data ###
+data/
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+.DS_Store
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+.venv_container
+.venv_whl
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.envrc
+.direnv/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# nix
+/result
+
+# tangram plugins
+*.sqlite3
+*.sqlite3-journal
+# End of https://www.toptal.com/developers/gitignore/api/python
+
+.npm/

tangram_explore-0.3.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: tangram-explore
+Version: 0.3.0
+Summary: Tangram plugin for exploring any Arrow-backed dataframe
+Requires-Python: >=3.10
+Requires-Dist: arro3-core>=0.4.0
+Requires-Dist: arro3-io>=0.4.0
+Requires-Dist: tangram-core>=0.2.1
+Provides-Extra: polars
+Requires-Dist: polars>=1; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# tangram_explore
+
+The `tangram_explore` plugin provides an interactive environment for data exploration and visualization within Tangram.
+
+It provides:
+
+- A Python API to generate interactive plots.
+- Real-time communication with the Tangram frontend.
+- Flexible layer-based visualization system.

tangram_explore-0.3.0/examples/basic.py

@@ -0,0 +1,35 @@
+import asyncio
+
+import numpy as np
+import polars as pl
+import tangram_core
+from tangram_core.config import CoreConfig
+from tangram_explore import ScatterLayer, Session
+
+
+async def main() -> None:
+    async with tangram_core.Runtime(
+        config=tangram_core.Config(core=CoreConfig(plugins=["tangram_explore"]))
+    ) as runtime:
+        session = Session(runtime.state)
+
+        x = np.linspace(-13, 13, 100)
+        await session.push(
+            ScatterLayer(
+                pl.DataFrame({"longitude": x, "latitude": x}),
+                fill_color="#027ec7",
+                label="NE-SW",
+            ),
+        )
+        await session.push(
+            ScatterLayer(
+                pl.DataFrame({"longitude": x, "latitude": -x}),
+                fill_color="#be4d5e",
+                label="NW-SE",
+            )
+        )
+        await runtime.wait()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tangram_explore-0.3.0/examples/basic_interactive.py

@@ -0,0 +1,36 @@
+# ruff: noqa: F704, E402
+# %%
+import numpy as np
+import polars as pl
+import tangram_core
+from tangram_core.config import CoreConfig
+
+runtime = tangram_core.Runtime(
+    config=tangram_core.Config(core=CoreConfig(plugins=["tangram_explore"]))
+)
+await runtime.start()
+# %%
+from tangram_explore import ScatterLayer, Session
+
+session = Session(runtime.state)
+
+x = np.linspace(-13, 13, 100)
+# %%
+await session.push(
+    ScatterLayer(
+        pl.DataFrame({"longitude": x, "latitude": x}),
+        fill_color="#027ec7",
+        label="NE-SW",
+    )
+)
+# %%
+await session.push(
+    ScatterLayer(
+        pl.DataFrame({"longitude": x, "latitude": -x}),
+        fill_color="#be4d5e",
+        label="NW-SE",
+    )
+)
+# %%
+await runtime.stop()
+# %%

tangram_explore-0.3.0/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@open-aviation/tangram-explore",
+  "version": "0.3.0",
+  "private": true,
+  "type": "module",
+  "description": "Explore flights in history",
+  "main": "src/tangram_explore/index.ts",
+  "license": "MIT",
+  "scripts": {
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@open-aviation/tangram-core": "workspace:*",
+    "apache-arrow": "^21.1.0",
+    "arrow-js-ffi": "^0.4.3"
+  },
+  "devDependencies": {
+    "@deck.gl/core": "^9.2.6",
+    "@deck.gl/extensions": "^9.2.6",
+    "@deck.gl/layers": "^9.2.6",
+    "parquet-wasm": "^0.7.1",
+    "vue": "^3.5.27"
+  }
+}

tangram_explore-0.3.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "tangram-explore"
+version = "0.3.0"
+description = "Tangram plugin for exploring any Arrow-backed dataframe"
+readme = "readme.md"
+requires-python = ">=3.10"
+# pyarrow is the gold standard for parquet serialisation but its very huge, keeping it minimal
+# we accept any object that adheres to the arrow C interface and thus do not require polars/pandas
+dependencies = ["tangram_core>=0.2.1", "arro3-core>=0.4.0", "arro3-io>=0.4.0"]
+
+[project.entry-points."tangram_core.plugins"]
+tangram_explore = "tangram_explore:plugin"
+
+[project.optional-dependencies]
+polars = ["polars>=1"]
+
+[tool.uv.sources]
+tangram_core = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

tangram_explore-0.3.0/readme.md

@@ -0,0 +1,9 @@
+# tangram_explore
+
+The `tangram_explore` plugin provides an interactive environment for data exploration and visualization within Tangram.
+
+It provides:
+
+- A Python API to generate interactive plots.
+- Real-time communication with the Tangram frontend.
+- Flexible layer-based visualization system.

tangram_explore-0.3.0/src/tangram_explore/ExploreLayers.vue

@@ -0,0 +1,172 @@
+<script setup lang="ts">
+import { watch, inject, onUnmounted, reactive, computed } from "vue";
+import { ScatterplotLayer } from "@deck.gl/layers";
+import type { PickingInfo } from "@deck.gl/core";
+import type { TangramApi, Disposable } from "@open-aviation/tangram-core/api";
+import { layers, parseColor, pluginConfig } from "./store";
+
+const api = inject<TangramApi>("tangramApi")!;
+const layerDisposables = new Map<string, Disposable>();
+
+const hoverInfo = reactive({
+  x: 0,
+  y: 0,
+  object: null as Record<string, unknown> | null,
+  layerLabel: ""
+});
+
+const enable3d = computed(() => {
+  if (pluginConfig.enable_3d === "inherit") return api.config.map.enable_3d;
+  return !!pluginConfig.enable_3d;
+});
+
+watch(
+  [layers, enable3d],
+  ([currentLayers, is3d]) => {
+    const activeIds = new Set(currentLayers.map(l => l.id));
+
+    for (const [id, disposable] of layerDisposables) {
+      if (!activeIds.has(id)) {
+        disposable.dispose();
+        layerDisposables.delete(id);
+      }
+    }
+
+    for (const entry of currentLayers) {
+      const table = entry.table;
+      const numRows = table.numRows;
+      const schema = table.schema;
+
+      const latField = schema.fields.find(
+        f => f.name === "latitude" || f.name === "lat"
+      )?.name;
+      const lonField = schema.fields.find(
+        f => f.name === "longitude" || f.name === "lon" || f.name === "lng"
+      )?.name;
+
+      let altField: string | undefined;
+      if (is3d) {
+        altField = schema.fields.find(
+          f => f.name === "altitude" || f.name === "alt" || f.name === "height"
+        )?.name;
+      }
+
+      if (!latField || !lonField) continue;
+
+      const latData = table.getChild(latField)!;
+      const lonData = table.getChild(lonField)!;
+      const altData = altField ? table.getChild(altField) : null;
+
+      if (entry.style.kind === "scatter") {
+        const opts = entry.style;
+        const deckLayer = new ScatterplotLayer({
+          id: `explore-layer-${entry.id}`,
+          data: { length: numRows },
+          visible: entry.visible,
+          pickable: opts.pickable,
+          opacity: opts.opacity,
+          stroked: opts.stroked,
+          filled: opts.filled,
+          radiusScale: opts.radius_scale,
+          radiusMinPixels: opts.radius_min_pixels,
+          radiusMaxPixels: opts.radius_max_pixels,
+          lineWidthMinPixels: opts.line_width_min_pixels,
+          // radiusUnits: "pixels",
+          getPosition: (_: unknown, { index }: { index: number }) => {
+            const lat = latData.get(index);
+            const lon = lonData.get(index);
+            const alt = altData ? altData.get(index) : 0;
+            return [lon, lat, alt];
+          },
+          getFillColor: parseColor(opts.fill_color, [255, 140, 0, 200]),
+          getLineColor: parseColor(opts.line_color, [0, 0, 0, 255]),
+          onHover: (info: PickingInfo) => {
+            if (info.index !== -1) {
+              const row = table.get(info.index);
+              hoverInfo.object = row ? row.toJSON() : null;
+              hoverInfo.x = info.x;
+              hoverInfo.y = info.y;
+              hoverInfo.layerLabel = entry.label;
+            } else {
+              hoverInfo.object = null;
+            }
+          },
+          updateTriggers: {
+            getPosition: [entry.id, is3d],
+            getFillColor: [entry.id, JSON.stringify(opts.fill_color)],
+            getLineColor: [entry.id, JSON.stringify(opts.line_color)]
+          }
+        });
+
+        if (!layerDisposables.has(entry.id)) {
+          layerDisposables.set(entry.id, api.map.setLayer(deckLayer));
+        } else {
+          api.map.setLayer(deckLayer);
+        }
+      }
+    }
+  },
+  { deep: true }
+);
+
+onUnmounted(() => {
+  for (const disposable of layerDisposables.values()) {
+    disposable.dispose();
+  }
+  layerDisposables.clear();
+});
+</script>
+
+<template>
+  <div
+    v-if="hoverInfo.object"
+    class="explore-tooltip"
+    :style="{ left: `${hoverInfo.x}px`, top: `${hoverInfo.y}px` }"
+  >
+    <div class="tooltip-header">{{ hoverInfo.layerLabel }}</div>
+    <div class="tooltip-grid">
+      <template v-for="(val, key) in hoverInfo.object" :key="key">
+        <div class="key">{{ key }}</div>
+        <div class="val">
+          {{ typeof val === "number" && !Number.isInteger(val) ? val.toFixed(4) : val }}
+        </div>
+      </template>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.explore-tooltip {
+  position: absolute;
+  background: white;
+  color: black;
+  padding: 6px 10px;
+  border-radius: 8px;
+  font-size: 11px;
+  font-family: "B612", sans-serif;
+  pointer-events: none;
+  transform: translate(12px, 12px);
+  z-index: 2000;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  border: 1px solid rgba(0, 0, 0, 0.05);
+  max-width: 250px;
+}
+
+.tooltip-header {
+  font-weight: bold;
+  padding-bottom: 4px;
+  color: #333;
+}
+
+.tooltip-grid {
+  display: grid;
+  grid-template-columns: auto auto;
+  column-gap: 12px;
+  row-gap: 1px;
+}
+
+.key {
+  text-align: right;
+  font-weight: 500;
+}
+</style>

tangram_explore-0.3.0/src/tangram_explore/LayerList.vue

@@ -0,0 +1,170 @@
+<template>
+  <div class="layer-list">
+    <div v-if="layers.length === 0" class="empty-state">no active layers</div>
+    <div v-for="layer in layers" :key="layer.id" class="layer-item">
+      <div class="left-col">
+        <button
+          class="visibility-btn"
+          :title="layer.visible ? 'hide layer' : 'show layer'"
+          @click="toggleLayerVisibility(layer.id)"
+        >
+          <svg
+            v-if="layer.visible"
+            xmlns="http://www.w3.org/2000/svg"
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <path
+              d="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0"
+            />
+            <circle cx="12" cy="12" r="3" />
+          </svg>
+          <svg
+            v-else
+            xmlns="http://www.w3.org/2000/svg"
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <path d="m15 18-.722-3.25" />
+            <path d="M2 8a10.645 10.645 0 0 0 20 0" />
+            <path d="m20 15-1.726-2.05" />
+            <path d="m4 15 1.726-2.05" />
+            <path d="m9 18 .722-3.25" />
+          </svg>
+        </button>
+        <span class="layer-label">{{ layer.label }}</span>
+      </div>
+      <div class="right-col">
+        <span class="layer-stats">{{ layer.table.numRows.toLocaleString() }} rows</span>
+        <div class="layer-chip">
+          <div
+            class="status-dot"
+            :style="{ backgroundColor: getLayerColor(layer.style) }"
+          ></div>
+          <span class="kind-label">{{ layer.style.kind }}</span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { layers, toggleLayerVisibility, parseColor, type StyleOptions } from "./store";
+
+function getLayerColor(style: StyleOptions): string {
+  let c;
+  if (style.kind === "scatter") {
+    c = style.fill_color;
+  } else {
+    c = [128, 128, 128];
+  }
+  const [r, g, b, a] = parseColor(c, [128, 128, 128, 255]);
+  return `rgba(${r}, ${g}, ${b}, ${a / 255})`;
+}
+</script>
+
+<style scoped>
+.layer-list {
+  display: flex;
+  flex-direction: column;
+  max-height: 300px;
+  overflow-y: auto;
+}
+
+.empty-state {
+  padding: 1rem;
+  text-align: center;
+  color: #666;
+  font-size: 0.9em;
+  font-style: italic;
+}
+
+.layer-item {
+  padding: 6px 12px;
+  border-bottom: 1px solid #eee;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  font-size: 0.9em;
+}
+
+.left-col {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 0;
+}
+
+.right-col {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-shrink: 0;
+}
+
+.visibility-btn {
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: 2px;
+  color: #888;
+  display: flex;
+  align-items: center;
+}
+
+.visibility-btn:hover {
+  color: #333;
+}
+
+.layer-label {
+  font-weight: 500;
+  color: #333;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-family: "B612", sans-serif;
+}
+
+.layer-chip {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  background-color: #f5f5f5;
+  padding: 2px 6px 2px 4px;
+  border-radius: 12px;
+  border: 1px solid #e0e0e0;
+}
+
+.status-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+}
+
+.kind-label {
+  text-transform: lowercase;
+  font-size: 0.75em;
+  color: #555;
+  font-weight: 600;
+  line-height: 1;
+}
+
+.layer-stats {
+  color: #999;
+  font-variant-numeric: tabular-nums;
+  font-size: 0.85em;
+}
+</style>

tangram_explore-0.3.0/src/tangram_explore/__init__.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import io
+import uuid
+from contextlib import asynccontextmanager
+from dataclasses import KW_ONLY, dataclass, field, fields, is_dataclass
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    AsyncGenerator,
+    Literal,
+    Protocol,
+    cast,
+    runtime_checkable,
+)
+
+import arro3.core as ac
+import arro3.io
+import orjson
+import tangram_core
+from fastapi import APIRouter
+from fastapi.responses import Response
+from tangram_core.config import ExposeField
+
+if TYPE_CHECKING:
+    from typing import TypeAlias
+
+    from tangram_core import BackendState
+
+EXPLORE_CHANNEL = "explore"
+EXPLORE_EVENT = "layers"
+
+router = APIRouter(prefix="/explore", tags=["explore"])
+
+
+LayerId: TypeAlias = str
+"""Unique UUID for a layer."""
+ParquetBytes: TypeAlias = bytes
+LayerConfig: TypeAlias = dict[str, Any]
+"""Serialised layer configuration without data or label."""
+
+
+@dataclass
+class ExploreState:
+    data: dict[LayerId, ParquetBytes] = field(default_factory=dict)
+    layers: dict[LayerId, LayerConfig] = field(default_factory=dict)
+    layer_order: list[LayerId] = field(default_factory=list)
+
+
+@asynccontextmanager
+async def lifespan(state: BackendState) -> AsyncGenerator[None, None]:
+    setattr(state, "explore_state", ExploreState())
+    yield
+    delattr(state, "explore_state")
+
+
+def get_explore_state(state: tangram_core.InjectBackendState) -> ExploreState:
+    return cast(ExploreState, getattr(state, "explore_state"))
+
+
+@router.get("/data/{data_id}")
+async def get_explore_data(
+    data_id: str, state: tangram_core.InjectBackendState
+) -> Response:
+    explore_state = get_explore_state(state)
+    data = explore_state.data.get(data_id)
+    if data is None:
+        return Response(status_code=404)  # shouldn't occur
+    return Response(content=data, media_type="application/vnd.apache.parquet")
+
+
+@router.get("/layers")
+async def get_layers(state: tangram_core.InjectBackendState) -> list[dict[str, Any]]:
+    explore_state = get_explore_state(state)
+    return [explore_state.layers[uid] for uid in explore_state.layer_order]
+
+
+@runtime_checkable
+class ArrowStreamExportable(Protocol):
+    def __arrow_c_stream__(self, requested_schema: Any = None) -> Any: ...
+
+
+@runtime_checkable
+class ExploreLayer(Protocol):
+    data: ArrowStreamExportable
+    """Any data structure that implements the
+    [Arrow C data interface](https://arrow.apache.org/docs/format/CDataInterface.html),
+    such as polars DataFrames or pyarrow Tables."""
+    label: str | None
+    """Unique name for the layer (optional).
+    If not provided, a random 8-character ID will be used."""
+
+
+@dataclass(frozen=True, slots=True)
+class ScatterLayer(ExploreLayer):
+    data: ArrowStreamExportable
+    _: KW_ONLY
+    radius_scale: float = 50.0
+    radius_min_pixels: float = 2.0
+    radius_max_pixels: float = 5.0
+    line_width_min_pixels: float = 1.0
+    fill_color: str | list[int] = "#027ec7"
+    line_color: str | list[int] = "#000000"
+    opacity: float = 0.8
+    stroked: bool = False
+    filled: bool = True
+    pickable: bool = True
+    label: str | None = None
+    kind: Literal["scatter"] = field(default="scatter", init=False)
+
+
+def _to_parquet_bytes(df: Any) -> bytes:
+    if not isinstance(df, ArrowStreamExportable):
+        raise TypeError(
+            f"cannot convert {type(df).__name__} to arrow. "
+            "object must implement '__arrow_c_stream__' protocol. "
+        )
+
+    reader = ac.RecordBatchReader.from_arrow(df)
+    sink = io.BytesIO()
+    arro3.io.write_parquet(reader, sink)
+    return sink.getvalue()
+
+
+@dataclass(frozen=True, slots=True)
+class Layer:
+    id: str
+    _session: Session
+
+    async def remove(self) -> None:
+        await self._session.remove(self.id)
+
+
+@dataclass(frozen=True, slots=True)
+class Session:
+    state: BackendState
+
+    def __post_init__(self) -> None:
+        if not hasattr(self.state, "explore_state"):
+            raise RuntimeError(
+                "The 'tangram_explore' plugin is not active. "
+                "Ensure it is added to the [core.plugins] list in your config."
+            )
+
+    async def _broadcast(self, op: str, **kwargs: Any) -> None:
+        payload = {"op": op, **kwargs}
+        topic = f"to:{EXPLORE_CHANNEL}:{EXPLORE_EVENT}"
+        await self.state.redis_client.publish(topic, orjson.dumps(payload))
+
+    async def push(self, layer: ExploreLayer) -> Layer:
+        if not is_dataclass(layer):  # required for fields()
+            raise TypeError("layer must be a dataclass")
+        if not isinstance(layer, ExploreLayer):
+            raise TypeError("layer must implement ExploreLayer protocol")
+
+        data_id = str(uuid.uuid4())
+        parquet_bytes = _to_parquet_bytes(layer.data)
+
+        explore_state = get_explore_state(self.state)
+        explore_state.data[data_id] = parquet_bytes
+
+        style = {
+            f.name: getattr(layer, f.name)
+            for f in fields(layer)
+            if f.name not in ("data", "label")
+        }
+        label = getattr(layer, "label", None)
+
+        layer_def = {
+            "id": data_id,
+            "label": label or data_id[:8],
+            "url": f"/explore/data/{data_id}",
+            "style": style,
+        }
+        explore_state.layers[data_id] = layer_def
+        explore_state.layer_order.append(data_id)
+
+        await self._broadcast("add", layer=layer_def)
+
+        return Layer(id=data_id, _session=self)
+
+    async def remove(self, data_id: str) -> None:
+        explore_state = get_explore_state(self.state)
+        if data_id in explore_state.data:
+            del explore_state.data[data_id]
+        if data_id in explore_state.layers:
+            del explore_state.layers[data_id]
+        if data_id in explore_state.layer_order:
+            explore_state.layer_order.remove(data_id)
+        await self._broadcast("remove", id=data_id)
+
+    async def clear(self) -> None:
+        explore_state = get_explore_state(self.state)
+        explore_state.data.clear()
+        explore_state.layers.clear()
+        explore_state.layer_order.clear()
+        await self._broadcast("clear")
+
+
+@dataclass
+class ExploreConfig:
+    enable_3d: Annotated[Literal["inherit"] | bool, ExposeField()] = "inherit"
+    """Whether to render scatter points in 3D"""
+
+
+plugin = tangram_core.Plugin(
+    frontend_path="dist-frontend",
+    routers=[router],
+    config_class=ExploreConfig,
+    lifespan=lifespan,
+)

tangram_explore-0.3.0/src/tangram_explore/index.ts

@@ -0,0 +1,96 @@
+import type { TangramApi } from "@open-aviation/tangram-core/api";
+import initWasm, { readParquet, wasmMemory } from "parquet-wasm";
+import { parseTable } from "arrow-js-ffi";
+import ExploreLayers from "./ExploreLayers.vue";
+import LayerList from "./LayerList.vue";
+import {
+  addLayer,
+  clearLayers,
+  removeLayer,
+  type StyleOptions,
+  pluginConfig
+} from "./store";
+
+const EXPLORE_CHANNEL = "explore";
+const EXPLORE_EVENT = "layers";
+
+let wasmInitialized = false;
+
+async function initParquetWasm() {
+  if (wasmInitialized) return;
+  await initWasm("/parquet_wasm_bg.wasm");
+  wasmInitialized = true;
+}
+
+interface LayerDefinition {
+  id: string;
+  label: string;
+  url: string;
+  style: StyleOptions;
+}
+
+interface StackMessage {
+  op: "add" | "remove" | "clear";
+  layer?: LayerDefinition;
+  id?: string;
+}
+
+async function loadAndAdd(def: LayerDefinition) {
+  const resp = await fetch(def.url);
+  const arrayBuffer = await resp.arrayBuffer();
+  const data = new Uint8Array(arrayBuffer);
+
+  const wasmTable = readParquet(data);
+  const ffiTable = wasmTable.intoFFI();
+  const memory = wasmMemory().buffer;
+
+  const arrowTable = parseTable(
+    memory,
+    ffiTable.arrayAddrs(),
+    ffiTable.schemaAddr(),
+    true // copying is required because adding new layers can grow wasm memory and detach
+  );
+  addLayer(def.id, def.label, arrowTable, wasmTable, def.style);
+}
+
+async function handleMessage(payload: StackMessage) {
+  if (payload.op === "add" && payload.layer) {
+    await loadAndAdd(payload.layer);
+  } else if (payload.op === "clear") {
+    clearLayers();
+  } else if (payload.op === "remove" && payload.id) {
+    removeLayer(payload.id);
+  }
+}
+
+async function syncLayers() {
+  const res = await fetch("/explore/layers");
+  const layerDefs: LayerDefinition[] = await res.json();
+  clearLayers();
+  for (const def of layerDefs) {
+    await loadAndAdd(def);
+  }
+}
+
+export async function install(
+  api: TangramApi,
+  config?: { enable_3d?: boolean | "inherit" }
+) {
+  if (config) {
+    if (config.enable_3d !== undefined) pluginConfig.enable_3d = config.enable_3d;
+  }
+
+  api.ui.registerWidget("explore-layers-map", "MapOverlay", ExploreLayers);
+  api.ui.registerWidget("explore-layers-list", "SideBar", LayerList, {
+    title: "Explore Layers"
+  });
+
+  await initParquetWasm();
+  await api.realtime.ensureConnected();
+
+  api.realtime.subscribe<StackMessage>(
+    `${EXPLORE_CHANNEL}:${EXPLORE_EVENT}`,
+    handleMessage
+  );
+  await syncLayers();
+}

tangram_explore-0.3.0/src/tangram_explore/store.ts

@@ -0,0 +1,96 @@
+import { reactive, shallowRef, triggerRef } from "vue";
+import type { Table } from "apache-arrow";
+import type { Table as WasmTable } from "parquet-wasm";
+
+export type ColorSpec =
+  | string
+  | [number, number, number]
+  | [number, number, number, number];
+
+export interface ScatterOptions {
+  kind: "scatter";
+  radius_scale: number;
+  radius_min_pixels: number;
+  radius_max_pixels: number;
+  line_width_min_pixels: number;
+  fill_color: ColorSpec;
+  line_color: ColorSpec;
+  opacity: number;
+  stroked: boolean;
+  filled: boolean;
+  pickable: boolean;
+}
+
+export type StyleOptions = ScatterOptions;
+
+export interface LayerEntry {
+  id: string;
+  label: string;
+  table: Table;
+  wasmRef: WasmTable;
+  style: StyleOptions;
+  visible: boolean;
+}
+
+export const layers = shallowRef<LayerEntry[]>([]);
+
+export const pluginConfig = reactive({
+  enable_3d: "inherit" as boolean | "inherit"
+});
+
+export function addLayer(
+  id: string,
+  label: string,
+  table: Table,
+  wasmRef: WasmTable,
+  style: StyleOptions
+) {
+  if (layers.value.some(d => d.id === id)) return;
+  layers.value.push({ id, label, table, wasmRef, style, visible: true });
+  triggerRef(layers);
+}
+
+export function removeLayer(id: string) {
+  const idx = layers.value.findIndex(d => d.id === id);
+  if (idx !== -1) {
+    const entry = layers.value[idx];
+    entry.wasmRef.free();
+    layers.value.splice(idx, 1);
+    triggerRef(layers);
+  }
+}
+
+export function clearLayers() {
+  layers.value.forEach(e => e.wasmRef.free());
+  layers.value = [];
+  triggerRef(layers);
+}
+
+export function toggleLayerVisibility(id: string) {
+  const layer = layers.value.find(d => d.id === id);
+  if (layer) {
+    layer.visible = !layer.visible;
+    triggerRef(layers);
+  }
+}
+
+export function parseColor(
+  c: ColorSpec,
+  defaultColor: [number, number, number, number]
+): [number, number, number, number] {
+  if (Array.isArray(c)) {
+    return c.length === 3
+      ? ([...c, 255] as [number, number, number, number])
+      : (c as [number, number, number, number]);
+  }
+  if (typeof c === "string" && c.startsWith("#")) {
+    const hex = c.slice(1);
+    if (hex.length === 6) {
+      const r = parseInt(hex.slice(0, 2), 16);
+      const g = parseInt(hex.slice(2, 4), 16);
+      const b = parseInt(hex.slice(4, 6), 16);
+      return [r, g, b, 255];
+    }
+  }
+  return defaultColor;
+}

tangram_explore-0.3.0/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import { tangramPlugin } from "@open-aviation/tangram-core/vite-plugin";
+
+export default defineConfig({
+  plugins: [tangramPlugin()]
+});