tangram-core 0.3.0__cp310-cp310-manylinux_2_28_aarch64.whl

tangram_core/plugin.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import asyncio
+import functools
+import importlib.metadata
+import logging
+import traceback
+from collections.abc import Callable, Coroutine
+from contextlib import AbstractAsyncContextManager
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, TypeAlias
+
+from fastapi import APIRouter
+
+if TYPE_CHECKING:
+    from .backend import BackendState
+
+    ServiceAsyncFunc: TypeAlias = Callable[[BackendState], Coroutine[Any, Any, None]]
+    ServiceFunc: TypeAlias = ServiceAsyncFunc | Callable[[BackendState], None]
+    Priority: TypeAlias = int
+    IntoFrontendConfigFunction: TypeAlias = Callable[[dict[str, Any]], Any]
+    Lifespan: TypeAlias = Callable[
+        [BackendState], AbstractAsyncContextManager[None, bool | None]
+    ]
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Plugin:
+    """Stores the metadata and registered API routes, background services and
+    frontend assets for a tangram plugin.
+
+    Packages should declare an entry point in the `tangram_core.plugins` group
+    in their `pyproject.toml` pointing to an instance of this class.
+    """
+
+    frontend_path: str | None = None
+    """Path to the compiled frontend assets, *relative* to the distribution root
+    (editable) or package root (wheel).
+    """
+    routers: list[APIRouter] = field(default_factory=list)
+    into_frontend_config_function: IntoFrontendConfigFunction | None = None
+    """Function to parse plugin-scoped backend configuration (within the
+    `tangram.toml`) into a frontend-safe configuration object.
+
+    If not specified, the backend configuration dict is passed as-is."""
+    lifespan: Lifespan | None = None
+    """Async context manager for plugin initialization and teardown."""
+    services: list[tuple[Priority, ServiceAsyncFunc]] = field(
+        default_factory=list, init=False
+    )
+    dist_name: str = field(init=False)
+    """Name of the distribution (package) that provided this plugin, populated
+    automatically during loading.
+    """  # we do this so plugins can know their own package name if needed
+
+    def register_service(
+        self, priority: Priority = 0
+    ) -> Callable[[ServiceFunc], ServiceFunc]:
+        """Decorator to register a background service function.
+
+        Services are long-running async functions that receive the BackendState
+        and are started when the application launches.
+        """
+
+        def decorator(func: ServiceFunc) -> ServiceFunc:
+            @functools.wraps(func)
+            async def async_wrapper(backend_state: BackendState) -> None:
+                if asyncio.iscoroutinefunction(func):
+                    await func(backend_state)
+                else:
+                    await asyncio.to_thread(func, backend_state)
+
+            self.services.append((priority, async_wrapper))
+            return func
+
+        return decorator
+
+
+def scan_plugins() -> importlib.metadata.EntryPoints:
+    return importlib.metadata.entry_points(group="tangram_core.plugins")
+
+
+def load_plugin(
+    entry_point: importlib.metadata.EntryPoint,
+) -> Plugin | None:
+    """Instantiates the plugin object defined in the entry point
+    and injects the name of the distribution into it."""
+    try:
+        plugin_instance = entry_point.load()
+    except Exception as e:
+        tb = traceback.format_exc()
+        logger.error(
+            f"failed to load plugin {entry_point.name}: {e}. {tb}"
+            f"\n= help: does {entry_point.value} exist?"
+        )
+        return None
+    if not isinstance(plugin_instance, Plugin):
+        logger.error(f"entry point {entry_point.name} is not an instance of `Plugin`")
+        return None
+    if entry_point.dist is None:
+        logger.error(f"could not determine distribution for plugin {entry_point.name}")
+        return None
+    # NOTE: we ignore `entry_point.name` for now and simply use the distribution's name
+    # should we raise an error if they differ? not for now
+
+    plugin_instance.dist_name = entry_point.dist.name
+    return plugin_instance

tangram_core/plugin.ts

@@ -0,0 +1,47 @@
+import type { TangramApi } from "./api";
+
+type PluginProgressStage = "manifest" | "plugin" | "done";
+type PluginProgress = {
+  stage: PluginProgressStage;
+  pluginName?: string;
+};
+
+export type PluginConfig = unknown; // to be casted by each plugin who consume it
+
+export async function loadPlugins(
+  tangramApi: TangramApi,
+  onProgress?: (progress: PluginProgress) => void
+) {
+  onProgress?.({ stage: "manifest" });
+  const manifest = await fetch("/manifest.json").then(res => res.json());
+
+  for (const [pluginName, meta] of Object.entries(manifest.plugins)) {
+    const pluginMeta = meta as {
+      main: string;
+      style?: string;
+      config?: PluginConfig;
+    };
+
+    onProgress?.({ stage: "plugin", pluginName });
+
+    if (pluginMeta.style) {
+      const link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.href = `/plugins/${pluginName}/${pluginMeta.style}`;
+      document.head.appendChild(link);
+    }
+
+    const entryPointUrl = `/plugins/${pluginName}/${pluginMeta.main}`;
+
+    try {
+      const pluginModule = await import(/* @vite-ignore */ entryPointUrl);
+      if (pluginModule.install) {
+        pluginModule.install(tangramApi, pluginMeta.config);
+      }
+    } catch (e) {
+      console.error(`failed to load plugin "${pluginName}":`, e);
+    }
+  }
+
+  onProgress?.({ stage: "done" });
+}

tangram_core/redis.py

@@ -0,0 +1,89 @@
+import abc
+import asyncio
+import logging
+from typing import Generic, List, TypeVar
+
+from redis.asyncio import Redis
+from redis.asyncio.client import PubSub
+from redis.exceptions import RedisError
+
+log = logging.getLogger(__name__)
+
+StateT = TypeVar("StateT")
+
+
+class Subscriber(abc.ABC, Generic[StateT]):
+    redis: Redis
+    task: asyncio.Task[None]
+    pubsub: PubSub
+
+    def __init__(
+        self, name: str, redis_url: str, channels: List[str], initial_state: StateT
+    ):
+        self.name = name
+        self.redis_url: str = redis_url
+        self.channels: List[str] = channels
+        self.state: StateT = initial_state
+        self._running = False
+
+    async def subscribe(self) -> None:
+        if self._running:
+            log.warning("%s already running", self.name)
+            return
+
+        try:
+            self.redis = await Redis.from_url(self.redis_url)
+            self.pubsub = self.redis.pubsub()
+            await self.pubsub.psubscribe(*self.channels)
+        except RedisError as e:
+            log.error("%s failed to connect to Redis: %s", self.name, e)
+            raise
+
+        async def listen() -> None:
+            try:
+                log.info("%s listening ...", self.name)
+                async for message in self.pubsub.listen():
+                    log.debug("message: %s", message)
+                    if message["type"] == "pmessage":
+                        await self.message_handler(
+                            message["channel"].decode("utf-8"),
+                            message["data"].decode("utf-8"),
+                            message["pattern"].decode("utf-8"),
+                            self.state,
+                        )
+            except asyncio.CancelledError:
+                log.warning("%s cancelled", self.name)
+
+        self._running = True
+
+        self.task = asyncio.create_task(listen())
+        log.info("%s task created, running ...", self.name)
+
+    async def cleanup(self) -> None:
+        if not self._running:
+            return
+
+        if self.task:
+            log.debug("%s canceling task ...", self.name)
+            self.task.cancel()
+            try:
+                log.debug("%s await task to finish ...", self.name)
+                await self.task
+                log.debug("%s task canceled", self.name)
+            except asyncio.CancelledError as exc:
+                log.error("%s task canceling error: %s", self.name, exc)
+        if self.pubsub:
+            await self.pubsub.unsubscribe()
+        if self.redis:
+            await self.redis.close()
+        self._running = False
+
+    def is_active(self) -> bool:
+        """Return True if the subscriber is actively listening."""
+        return self._running and self.task is not None and not self.task.done()
+
+    @abc.abstractmethod
+    async def message_handler(
+        self, event: str, payload: str, pattern: str, state: StateT
+    ) -> None:
+        pass

tangram_core/user.css

@@ -0,0 +1,114 @@
+html,
+body,
+#container-map {
+  height: 100%;
+  overflow: hidden;
+  width: 100%;
+}
+
+#map {
+  box-shadow: 0 0 10px rgba(0, 0, 0, 0.5);
+  height: 100%;
+  width: auto;
+}
+
+
+#chart {
+  border: none;
+}
+
+div.form {
+  float: right;
+  clear: right;
+  width: 300px;
+  border: 1px solid #bab0ac;
+  padding: 10px;
+}
+
+body {
+  font-family: "B612", sans-serif;
+}
+
+span.monospace {
+  font-family: "B612", sans-serif;
+  font-size: 85%;
+}
+
+.smaller td {
+  font-size: 95%;
+}
+
+table a:not(.btn),
+.table a:not(.btn) {
+  text-decoration: none;
+}
+
+a.flag {
+  position: relative;
+  cursor: pointer;
+  color: #2c3e50;
+}
+
+a.flag:hover::after {
+  content: attr(data-tooltip);
+  position: absolute;
+  bottom: 1.7em;
+  left: 0.5em;
+  border: 1px #18bc9c solid;
+  border-radius: 5px;
+  padding: 4px;
+  color: whitesmoke;
+  background-color: #18bc9c;
+  text-align: center;
+  font-size: 90%;
+  width: max-content;
+  z-index: 1;
+}
+
+.w20pc {
+  width: 20%;
+}
+
+.center {
+  margin-top: 20px;
+  margin-left: auto;
+  margin-right: auto;
+  /* max-width: 1000px; */
+}
+
+.copyright_label {
+  display: inline;
+  padding: 0.2em 0.6em 0.3em;
+  font-size: 75%;
+  font-weight: 400;
+  line-height: 1;
+  color: #fff;
+  text-align: center;
+  white-space: nowrap;
+  vertical-align: baseline;
+  border-radius: 0.25em;
+  position: absolute;
+  bottom: 0;
+  z-index: 1;
+}
+
+.turb_selected {
+  stroke: red;
+  stroke-width: 15px;
+  z-index: -1;
+}
+
+.form-popup {
+  display: none;
+  position: fixed;
+  bottom: 0;
+  right: 15px;
+  border: 3px solid #f1f1f1;
+  z-index: 9;
+}
+
+.form-container {
+  max-width: 300px;
+  padding: 10px;
+  background-color: white;
+}

tangram_core/utils.ts

@@ -0,0 +1,143 @@
+// adapted from: https://github.com/color-js/color.js/blob/main/src/spaces/oklch.js
+type Vector3 = [number, number, number];
+
+const multiplyMatrices = (A: number[], B: Vector3): Vector3 => {
+  return [
+    A[0] * B[0] + A[1] * B[1] + A[2] * B[2],
+    A[3] * B[0] + A[4] * B[1] + A[5] * B[2],
+    A[6] * B[0] + A[7] * B[1] + A[8] * B[2]
+  ];
+};
+
+const oklch2oklab = ([l, c, h]: Vector3): Vector3 => [
+  l,
+  isNaN(h) ? 0 : c * Math.cos((h * Math.PI) / 180),
+  isNaN(h) ? 0 : c * Math.sin((h * Math.PI) / 180)
+];
+
+const srgbLinear2rgb = (rgb: Vector3): Vector3 =>
+  rgb.map(c =>
+    Math.abs(c) > 0.0031308
+      ? (c < 0 ? -1 : 1) * (1.055 * Math.pow(Math.abs(c), 1 / 2.4) - 0.055)
+      : 12.92 * c
+  ) as Vector3;
+
+const oklab2xyz = (lab: Vector3): Vector3 => {
+  const LMSg = multiplyMatrices(
+    [
+      1, 0.3963377773761749, 0.2158037573099136, 1, -0.1055613458156586,
+      -0.0638541728258133, 1, -0.0894841775298119, -1.2914855480194092
+    ],
+    lab
+  );
+  const LMS = LMSg.map(val => val ** 3) as Vector3;
+  return multiplyMatrices(
+    [
+      1.2268798758459243, -0.5578149944602171, 0.2813910456659647, -0.0405757452148008,
+      1.112286803280317, -0.0717110580655164, -0.0763729366746601, -0.4214933324022432,
+      1.5869240198367816
+    ],
+    LMS
+  );
+};
+
+const xyz2rgbLinear = (xyz: Vector3): Vector3 => {
+  return multiplyMatrices(
+    [
+      3.2409699419045226, -1.537383177570094, -0.4986107602930034, -0.9692436362808796,
+      1.8759675015077202, 0.04155505740717559, 0.05563007969699366,
+      -0.20397695888897652, 1.0569715142428786
+    ],
+    xyz
+  );
+};
+
+export const oklch2rgb = (lch: Vector3): Vector3 =>
+  srgbLinear2rgb(xyz2rgbLinear(oklab2xyz(oklch2oklab(lch))));
+
+export function oklchToDeckGLColor(
+  l: number,
+  c: number,
+  h: number,
+  a: number = 255
+): [number, number, number, number] {
+  const rgb = oklch2rgb([l, c, h]);
+  return [
+    Math.max(0, Math.min(255, Math.round(rgb[0] * 255))),
+    Math.max(0, Math.min(255, Math.round(rgb[1] * 255))),
+    Math.max(0, Math.min(255, Math.round(rgb[2] * 255))),
+    a
+  ];
+}
+
+export const formatTime = (ts: string) => {
+  const d = new Date(ts + "Z");
+  return (
+    d.toLocaleString("en-GB", {
+      timeZone: "UTC",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit"
+    }) + "Z"
+  );
+};
+
+export const formatDuration = (sec: number) => {
+  const h = Math.floor(sec / 3600);
+  const m = Math.floor((sec % 3600) / 60);
+  return `${h}h ${m}m`;
+};
+
+export type Position3D = [number, number, number];
+export interface PathSegment<ColorT> {
+  path: Position3D[];
+  colors: ColorT[];
+  dashed: boolean;
+}
+
+export function* generateSegments<T, ColorT>(
+  data: Iterable<T>,
+  opts: {
+    getPosition: (d: T) => Position3D | null;
+    getTimestamp: (d: T) => number | null;
+    getColor: (d: T) => ColorT;
+    gapColor: ColorT;
+    maxGapSeconds: number;
+  }
+): Generator<PathSegment<ColorT>> {
+  let segment: PathSegment<ColorT> = { path: [], colors: [], dashed: false };
+  let lastT: number | null = null;
+  let lastPos: Position3D | null = null;
+
+  for (const d of data) {
+    const pos = opts.getPosition(d);
+    if (!pos) continue;
+
+    const t = opts.getTimestamp(d);
+
+    if (lastT !== null && t !== null && lastPos !== null) {
+      if (Math.abs(t - lastT) > opts.maxGapSeconds) {
+        if (segment.path.length > 1) {
+          yield segment;
+        }
+        yield {
+          path: [lastPos, pos],
+          colors: [opts.gapColor, opts.gapColor],
+          dashed: true
+        };
+        segment = { path: [], colors: [], dashed: false };
+      }
+    }
+
+    segment.path.push(pos);
+    segment.colors.push(opts.getColor(d));
+
+    lastT = t;
+    lastPos = pos;
+  }
+
+  if (segment.path.length > 1) {
+    yield segment;
+  }
+}

tangram_core/vite-plugin-tangram.mjs

@@ -0,0 +1,155 @@
+// not using typescript because of an annoying vite bug:
+// - https://github.com/vitejs/vite/issues/5370
+// - https://github.com/vitejs/vite/issues/16040
+// essentially, vite's on-the-fly transpilation is scoped only to the config
+// file itself. therefore vite plugins in a monorepo cannot be typescript.
+import vue from "@vitejs/plugin-vue";
+import path from "path";
+import fs from "fs/promises";
+
+const DECKGL_PACKAGES = [
+  "@deck.gl/core",
+  "@deck.gl/layers",
+  "@deck.gl/aggregation-layers",
+  "@deck.gl/geo-layers",
+  "@deck.gl/mesh-layers",
+  "@deck.gl/json",
+  "@deck.gl/mapbox",
+  "@deck.gl/widgets",
+  "@deck.gl/extensions"
+];
+
+/**
+ * @param {{ copyToPythonPackage?: boolean; pythonPackageDir?: string; includePackageJson?: boolean }} [options]
+ * If the plugin is built with maturin, `copyToPythonPackage` should be 'true' to
+ * avoid the built binary distribution wheel omitting the 'dist-frontend'.
+ * See: https://github.com/open-aviation/tangram/pull/99#issuecomment-3777038726
+ * @returns {import('vite').Plugin[]}
+ */
+export function tangramPlugin(options = {}) {
+  const projectRoot = process.cwd();
+  const copyToPythonPackage = options.copyToPythonPackage ?? false;
+  const includePackageJson = options.includePackageJson ?? true;
+  /** @type {{ name: string; main: string; }} */
+  let pkg;
+  let entryFileName;
+
+  /** @type {import('vite').Plugin} */
+  const configInjector = {
+    name: "tangram-plugin-config-injector",
+    async config() {
+      const pkgPath = path.resolve(projectRoot, "package.json");
+      pkg = JSON.parse(await fs.readFile(pkgPath, "utf-8"));
+
+      if (!pkg.main) {
+        throw new Error(
+          `\`main\` field must be specified in ${pkg.name}'s package.json`
+        );
+      }
+      entryFileName = path.parse(pkg.main).name;
+
+      /** @type {import('vite').UserConfig} */
+      const tangramBuildConfig = {
+        build: {
+          sourcemap: true,
+          lib: {
+            entry: pkg.main,
+            fileName: entryFileName,
+            formats: ["es"]
+          },
+          rollupOptions: {
+            external: [
+              "vue",
+              "maplibre",
+              ...DECKGL_PACKAGES,
+              "lit-html",
+              "rs1090-wasm",
+              "parquet-wasm"
+            ]
+          },
+          outDir: "dist-frontend",
+          minify: true
+        }
+      };
+      return tangramBuildConfig;
+    }
+  };
+
+  /** @type {import('vite').Plugin} */
+  const manifestGenerator = {
+    name: "tangram-manifest-generator",
+    apply: "build",
+    async writeBundle(outputOptions, bundle) {
+      const outDir = outputOptions.dir;
+      const cssAsset = Object.values(bundle).find(
+        asset => asset.type === "asset" && asset.fileName.endsWith(".css")
+      );
+
+      const manifest = {
+        name: pkg.name,
+        main: `${entryFileName}.js`,
+        ...(cssAsset && { style: cssAsset.fileName })
+      };
+      await fs.writeFile(
+        path.resolve(outDir, "plugin.json"),
+        JSON.stringify(manifest, null, 2)
+      );
+    }
+  };
+
+  /** @type {import('vite').Plugin} */
+  const pythonPackageSync = {
+    name: "tangram-python-package-sync",
+    apply: "build",
+    async writeBundle(outputOptions) {
+      if (!copyToPythonPackage) return;
+
+      const outDir = outputOptions.dir
+        ? path.resolve(projectRoot, outputOptions.dir)
+        : path.resolve(projectRoot, "dist-frontend");
+      const pythonPackageDir = options.pythonPackageDir
+        ? path.resolve(projectRoot, options.pythonPackageDir)
+        : path.resolve(projectRoot, path.dirname(pkg.main));
+      const distDst = path.join(pythonPackageDir, "dist-frontend");
+
+      try {
+        await fs.stat(outDir);
+      } catch {
+        return;
+      }
+
+      await fs.rm(distDst, { recursive: true, force: true });
+      await copyDirRecursive(outDir, distDst);
+
+      if (includePackageJson) {
+        await fs.copyFile(
+          path.resolve(projectRoot, "package.json"),
+          path.join(pythonPackageDir, "package.json")
+        );
+      }
+    }
+  };
+
+  return [vue(), configInjector, manifestGenerator, pythonPackageSync];
+}
+
+/**
+ * @param {string} src
+ * @param {string} dst
+ */
+async function copyDirRecursive(src, dst) {
+  await fs.mkdir(dst, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const dstPath = path.join(dst, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirRecursive(srcPath, dstPath);
+    } else if (entry.isFile()) {
+      await fs.mkdir(path.dirname(dstPath), { recursive: true });
+      await fs.copyFile(srcPath, dstPath);
+    }
+  }
+}