pluot_core 0.0.1__tar.gz

pluot_core-0.0.1/.gitignore

@@ -0,0 +1,71 @@
+/target
+target/
+**/*.rs.bk
+Cargo.lock
+bin/
+pkg/
+wasm-pack.log
+.DS_Store
+node_modules/
+
+crates/LICENSE
+dist/
+dist-tsc/
+tsconfig.tsbuildinfo
+data/out/
+
+zarrs/
+
+__pycache__/
+.pytest_cache/
+.ipynb_checkpoints/
+*.so
+.venv/
+.ropeproject/
+__marimo__/
+bindings-python/pluot_widget/src/pluot_widget/static/
+.Rproj.user
+
+.astro/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.env
+.env.production
+
+# Snapshot test outputs (reference snapshots are in tests/snapshots/)
+current/
+snaps-dirty/
+
+skills-lock.json
+.claude/settings.local.json
+.claude/scheduled_tasks.lock
+.claude/skills/autoresearch
+.agents/
+
+# R stuff
+.Rhistory
+.Rproj.user
+*.o
+AUTHORS
+*.tar.gz
+*.Rcheck
+
+
+autoresearch/
+circle_diffs/
+text_diffs/
+
+crates/pluot_core/src/vendored-fonts/*.ttf
+bindings-js/core/src/vendored-fonts/*.ttf.js
+bindings-r/src/.cargo/
+
+.pluot_integration_test_*.sh
+
+
+bindings-js/**/CHANGELOG.md
+crates/**/CHANGELOG.md
+RELEASE_NOTES.md
+
+references/

pluot_core-0.0.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: pluot_core
+Version: 0.0.1
+Summary: Shared utilities used by the pluot and pluot_widget packages
+Project-URL: repository, https://github.com/keller-mark/pluot
+Author: Mark Keller
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2
+Requires-Dist: obstore
+Requires-Dist: zarr>=3
+Description-Content-Type: text/markdown
+
+This pluot_core package will contain all shared functionality that is used by the pluot and pluot_widget packages, such as zarr and font stuff and viewport utilities.

pluot_core-0.0.1/README.md

@@ -0,0 +1 @@
+This pluot_core package will contain all shared functionality that is used by the pluot and pluot_widget packages, such as zarr and font stuff and viewport utilities.

pluot_core-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pluot_core"
+version = "0.0.1"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [
+  {name = "Mark Keller"}
+]
+readme = "README.md"
+description = "Shared utilities used by the pluot and pluot_widget packages"
+dependencies = [
+  "numpy>=2",
+  "zarr>=3",
+  "obstore",
+]
+
+[project.urls]
+repository = "https://github.com/keller-mark/pluot"

pluot_core-0.0.1/src/pluot_core/font.py

@@ -0,0 +1,138 @@
+import os
+import re
+import sys
+from pathlib import Path
+
+# TODO: use matplotlib's FontManager?
+# Reference: https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/font_manager.py
+# But this would introduce a matplotlib dependency.
+# Is there a more lightweight alternative?
+
+# Optional path overrides: font_family -> file path.
+# Takes priority over system font detection.
+_FONT_OVERRIDES: dict[str, str] = {}
+
+def register_font(font_name: str, path: str) -> None:
+    """Override the file path used for a named font. Takes priority over system detection."""
+    _FONT_OVERRIDES[font_name] = path
+
+def _normalize(name: str) -> str:
+    return re.sub(r'[\s\-_]', '', name).lower()
+
+
+# OS Font paths
+try:
+    _HOME = Path.home()
+except Exception:  # Exceptions thrown by home() are not specified...
+    _HOME = Path(os.devnull)  # Just an arbitrary path with no children.
+MSFolders = \
+    r'Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders'
+MSFontDirectories = [
+    r'SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts',
+    r'SOFTWARE\Microsoft\Windows\CurrentVersion\Fonts']
+MSUserFontDirectories = [
+    str(_HOME / 'AppData/Local/Microsoft/Windows/Fonts'),
+    str(_HOME / 'AppData/Roaming/Microsoft/Windows/Fonts'),
+]
+X11FontDirectories = [
+    # an old standard installation point
+    "/usr/X11R6/lib/X11/fonts/TTF/",
+    "/usr/X11/lib/X11/fonts",
+    # here is the new standard location for fonts
+    "/usr/share/fonts/",
+    # documented as a good place to install new fonts
+    "/usr/local/share/fonts/",
+    # common application, not really useful
+    "/usr/lib/openoffice/share/fonts/truetype/",
+    # user fonts
+    str((Path(os.environ.get('XDG_DATA_HOME') or _HOME / ".local/share"))
+        / "fonts"),
+    str(_HOME / ".fonts"),
+]
+OSXFontDirectories = [
+    "/Library/Fonts/",
+    "/Network/Library/Fonts/",
+    "/System/Library/Fonts/",
+    # fonts installed via MacPorts
+    "/opt/local/share/fonts",
+    # user fonts
+    str(_HOME / "Library/Fonts"),
+]
+
+def _system_font_dirs() -> list[Path]:
+    if sys.platform == 'darwin':
+        return [Path(d) for d in OSXFontDirectories]
+    elif sys.platform == 'win32':
+        return [Path(d) for d in MSUserFontDirectories]
+    else:  # Linux / other
+        return [Path(d) for d in X11FontDirectories]
+
+def _find_system_font(font_name: str) -> str | None:
+    norm_name = _normalize(font_name)
+    for font_dir in _system_font_dirs():
+        if not font_dir.exists():
+            continue
+        for path in font_dir.rglob('*'):
+            if path.suffix.lower() not in ('.ttf', '.otf'):
+                continue
+            if _normalize(path.stem) == norm_name:
+                return str(path)
+    return None
+
+# Cache results of _find_system_font to avoid redundant directory scans.
+_FONT_PATH_CACHE: dict[str, str | None] = {}
+
+def _resolve_font_path(font_name: str) -> str | None:
+    """Return the file path for a font.
+
+    Lookup order:
+    1. Explicit override registered via register_font().
+    2. System font detection.
+    """
+    if font_name in _FONT_OVERRIDES:
+        return _FONT_OVERRIDES[font_name]
+    if font_name not in _FONT_PATH_CACHE:
+        _FONT_PATH_CACHE[font_name] = _find_system_font(font_name)
+    return _FONT_PATH_CACHE[font_name]
+
+def _key_to_font_family(key: str) -> str:
+    """Extract the font family from a zarr-style key.
+
+    Keys use the format "{family}/{style}/{weight}.ttf". The family is the
+    first path segment. A leading "/" is stripped defensively if present.
+    """
+    # Strip any accidental leading slash then drop trailing .ttf/.otf.
+    name = key.lstrip('/')
+    if name.lower().endswith('.ttf') or name.lower().endswith('.otf'):
+        name = name[:-4]
+    # First segment is the family; remaining segments are style and weight.
+    return name.split('/')[0]
+
+class _BytesBuffer:
+    """Minimal buffer wrapper compatible with zarr.py's `.to_bytes()` protocol."""
+    def __init__(self, data: bytes):
+        self._data = data
+    def to_bytes(self) -> bytes:
+        return self._data
+
+class FontStore:
+    """
+    Store for fonts, registered as '__fonts__' in GLOBAL_STORES.
+    Rust requests fonts via zarr_get_status / zarr_get with store_name='__fonts__'
+    and key='{family}/{weight}/{style}.ttf'. The get_sync method is called by
+    zarr_get_status to eagerly resolve synchronous results without waiting for
+    an async call.
+    """
+
+    def get_sync(self, key: str) -> bytes:
+        """Synchronously return font bytes, or raise if unavailable."""
+        font_family = _key_to_font_family(key)
+        path = _resolve_font_path(font_family)
+        if path is None:
+            raise FileNotFoundError(f"Font not found: {font_family}")
+        with open(path, 'rb') as f:
+            return f.read()
+
+    async def get(self, key: str, prototype=None, byte_range=None) -> _BytesBuffer:
+        """Async fallback for zarr_get cache-miss path."""
+        return _BytesBuffer(self.get_sync(key))

pluot_core-0.0.1/src/pluot_core/sync_store.py

@@ -0,0 +1,68 @@
+# Copied from zarr-python
+# Reference: https://github.com/zarr-developers/zarr-python/blob/fe229107f9915f05817f7a664d3550695ff9ca44/src/zarr/testing/stateful.py#L438
+
+import builtins
+from typing import Any
+import zarr
+from zarr.abc.store import Store
+from zarr.core.buffer import Buffer, BufferPrototype
+
+
+class SyncStoreWrapper(zarr.core.sync.SyncMixin):
+    def __init__(self, store: Store) -> None:
+        """Synchronous Store wrapper
+
+        This class holds synchronous methods that map to async methods of Store classes.
+        The synchronous wrapper is needed because hypothesis' stateful testing infra does
+        not support asyncio so we redefine sync versions of the Store API.
+        https://github.com/HypothesisWorks/hypothesis/issues/3712#issuecomment-1668999041
+        """
+        self.store = store
+
+    @property
+    def read_only(self) -> bool:
+        return self.store.read_only
+
+    def set(self, key: str, data_buffer: Buffer) -> None:
+        return self._sync(self.store.set(key, data_buffer))
+
+    def list(self) -> builtins.list[str]:
+        return self._sync_iter(self.store.list())
+
+    def get(self, key: str, prototype: BufferPrototype, **kwargs) -> Buffer | None:
+        return self._sync(self.store.get(key, prototype=prototype, **kwargs))
+
+    def get_partial_values(
+        self, key_ranges: builtins.list[Any], prototype: BufferPrototype
+    ) -> builtins.list[Buffer | None]:
+        return self._sync(self.store.get_partial_values(prototype=prototype, key_ranges=key_ranges))
+
+    def delete(self, path: str) -> None:
+        return self._sync(self.store.delete(path))
+
+    def is_empty(self, prefix: str) -> bool:
+        return self._sync(self.store.is_empty(prefix=prefix))
+
+    def clear(self) -> None:
+        return self._sync(self.store.clear())
+
+    def exists(self, key: str) -> bool:
+        return self._sync(self.store.exists(key))
+
+    def list_dir(self, prefix: str) -> None:
+        raise NotImplementedError
+
+    def list_prefix(self, prefix: str) -> None:
+        raise NotImplementedError
+
+    @property
+    def supports_listing(self) -> bool:
+        return self.store.supports_listing
+
+    @property
+    def supports_writes(self) -> bool:
+        return self.store.supports_writes
+
+    @property
+    def supports_deletes(self) -> bool:
+        return self.store.supports_deletes

pluot_core-0.0.1/src/pluot_core/viewport.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+from typing import Literal, Optional
+from dataclasses import dataclass, field
+import numpy as np
+
+# TODO: auto-generate these types from the Rust side: https://github.com/keller-mark/pluot/issues/133
+AspectRatioMode = Literal["Ignore", "Contain", "Cover"]
+AspectRatioAlignmentMode = Literal["Center", "Start", "End"]
+
+
+@dataclass
+class Margins:
+    margin_top: float = 0.0
+    margin_right: float = 0.0
+    margin_bottom: float = 0.0
+    margin_left: float = 0.0
+
+
+@dataclass
+class ViewportParams:
+    width: float
+    height: float
+    aspect_ratio_mode: AspectRatioMode
+    aspect_ratio_alignment_mode: AspectRatioAlignmentMode
+    margins: Optional[Margins] = field(default=None)
+
+
+@dataclass
+class Bounds:
+    # Each value is optional.
+    # When an entire dimension is omitted (X or Y),
+    # use the current camera settings for that dimension.
+    # When a single value is omitted (e.g., x_min), ensure the resulting camera matrix keeps this boundary unchanged.
+    x_min: Optional[float] = None
+    x_max: Optional[float] = None
+    y_min: Optional[float] = None
+    y_max: Optional[float] = None
+
+
+def _get_scales_and_align_translations(viewport_params: ViewportParams):
+    margins = viewport_params.margins
+    margin_top = margins.margin_top if margins else 0.0
+    margin_right = margins.margin_right if margins else 0.0
+    margin_bottom = margins.margin_bottom if margins else 0.0
+    margin_left = margins.margin_left if margins else 0.0
+
+    layer_w = viewport_params.width - margin_left - margin_right
+    layer_h = viewport_params.height - margin_top - margin_bottom
+    layer_aspect_ratio = layer_w / layer_h
+
+    x_scale = 1.0
+    y_scale = 1.0
+    if viewport_params.aspect_ratio_mode == "Contain":
+        if layer_aspect_ratio > 1.0:
+            x_scale = layer_aspect_ratio
+        elif layer_aspect_ratio < 1.0:
+            y_scale = 1.0 / layer_aspect_ratio
+    elif viewport_params.aspect_ratio_mode == "Cover":
+        if layer_aspect_ratio > 1.0:
+            y_scale = 1.0 / layer_aspect_ratio
+        elif layer_aspect_ratio < 1.0:
+            x_scale = layer_aspect_ratio
+
+    x_align_translation = 0.0
+    y_align_translation = 0.0
+    if viewport_params.aspect_ratio_alignment_mode == "Start":
+        x_align_translation = x_scale - 1.0
+        y_align_translation = y_scale - 1.0
+    elif viewport_params.aspect_ratio_alignment_mode == "End":
+        x_align_translation = 1.0 - x_scale
+        y_align_translation = 1.0 - y_scale
+
+    return x_scale, y_scale, x_align_translation, y_align_translation
+
+
+def get_bounds(camera_matrix: np.ndarray, viewport_params: ViewportParams) -> Bounds:
+    """Calculate the visible data range based on camera view and viewport parameters."""
+    zoom_x = camera_matrix[0]
+    zoom_y = camera_matrix[5]
+    translate_x = camera_matrix[12]
+    translate_y = camera_matrix[13]
+
+    x_scale, y_scale, x_align_translation, y_align_translation = _get_scales_and_align_translations(viewport_params)
+
+    x_adj = x_scale - 1.0
+    y_adj = y_scale - 1.0
+
+    x_min = ((-translate_x - 1.0 - x_adj + x_align_translation) / zoom_x + 1.0) / 2.0
+    x_max = ((-translate_x + 1.0 + x_adj + x_align_translation) / zoom_x + 1.0) / 2.0
+    y_min = ((-translate_y - 1.0 - y_adj + y_align_translation) / zoom_y + 1.0) / 2.0
+    y_max = ((-translate_y + 1.0 + y_adj + y_align_translation) / zoom_y + 1.0) / 2.0
+
+    return Bounds(x_min=x_min, x_max=x_max, y_min=y_min, y_max=y_max)
+
+
+def get_camera_matrix_from_bounds(bounds: Bounds, prev_camera_matrix: np.ndarray, viewport_params: ViewportParams) -> np.ndarray:
+    """Given data bounds, compute the corresponding camera matrix.
+    Missing bound values are filled in from prev_camera_matrix.
+    """
+    current_bounds = get_bounds(prev_camera_matrix, viewport_params)
+    x_min = bounds.x_min if bounds.x_min is not None else current_bounds.x_min
+    x_max = bounds.x_max if bounds.x_max is not None else current_bounds.x_max
+    y_min = bounds.y_min if bounds.y_min is not None else current_bounds.y_min
+    y_max = bounds.y_max if bounds.y_max is not None else current_bounds.y_max
+
+    x_scale, y_scale, x_align_translation, y_align_translation = _get_scales_and_align_translations(viewport_params)
+
+    x_adj = x_scale - 1.0
+    y_adj = y_scale - 1.0
+
+    x_range = x_max - x_min
+    y_range = y_max - y_min
+
+    zoom_x = (1.0 + x_adj) / x_range
+    zoom_y = (1.0 + y_adj) / y_range
+
+    # When aspect ratio is ignored, zoom each axis independently.
+    # Otherwise take the minimum so all requested data fits within the viewport.
+    if viewport_params.aspect_ratio_mode != "Ignore":
+        zoom_x = zoom_y = min(zoom_x, zoom_y)
+
+    # Invert the get_bounds translation equations:
+    #   min + max = (-translate + align) / zoom + 1.0
+    # So: translate = align - zoom * ((min + max) - 1.0)
+    translate_x = x_align_translation - zoom_x * ((x_min + x_max) - 1.0)
+    translate_y = y_align_translation - zoom_y * ((y_min + y_max) - 1.0)
+
+    return np.array([
+        zoom_x, 0.0,   0.0, 0.0,
+        0.0,   zoom_y, 0.0, 0.0,
+        0.0,   0.0,    1.0, 0.0,
+        translate_x, translate_y, 0.0, 1.0,
+    ], dtype=np.float32)

pluot_core-0.0.1/src/pluot_core/zarr.py

@@ -0,0 +1,121 @@
+def store_instance_to_metadata(store) -> dict:
+    """Derive portable ``ZarrStoreInfo`` metadata from a zarr-python store instance.
+
+    The result mirrors the Rust ``ZarrStoreInfo`` JSON (see
+    ``crates/pluot_core/src/params.rs``): an adjacently-tagged ``store_type`` /
+    ``store_params`` pair plus an optional ``store_extensions`` list.
+
+    Resolution order:
+      1. A wrapper store may declare its own metadata via a ``store_metadata``
+         attribute (see :func:`store_with_metadata`), which already passes the
+         inner store's metadata through and layers on any extension.
+      2. A ``LocalStore`` exposes ``.root`` -> ``LocalStore``.
+      3. An fsspec/remote-backed store yields a URL -> ``HttpStore``.
+      4. Otherwise fall back to a ``MemoryStore`` descriptor. The instance is
+         still usable at render time (it is registered by name in
+         ``GLOBAL_STORES``), but its data is not reconstructable from metadata.
+    """
+    declared = getattr(store, "store_metadata", None)
+    if isinstance(declared, dict) and "store_type" in declared:
+        return declared
+
+    # LocalStore exposes `.root` (a path).
+    root = getattr(store, "root", None)
+    if root is not None:
+        return {
+            "store_type": "LocalStore",
+            "store_params": {"path": str(root)},
+            "store_extensions": None,
+        }
+
+    # Remote / fsspec-backed stores: derive a URL where possible.
+    url = _derive_store_url(store)
+    if url is not None:
+        return {
+            "store_type": "HttpStore",
+            "store_params": {"url": url},
+            "store_extensions": None,
+        }
+
+    return {
+        "store_type": "MemoryStore",
+        "store_params": {
+            "message": f"In-memory or custom store ({type(store).__name__})"
+        },
+        "store_extensions": None,
+    }
+
+
+# Registry of store-extension appliers used by store_metadata_to_instance to
+# reconstruct virtual-zarr wrapper stores (the inverse of the store_extensions
+# recorded by store_instance_to_metadata). Appliers are opt-in so this package
+# need not depend on every virtual-zarr implementation.
+_STORE_EXTENSION_APPLIERS: dict = {}
+
+
+def register_store_extension(extension: str, applier) -> None:
+    """Register the applier used to reconstruct a ``ZarrStoreExtension`` wrapper.
+
+    ``applier`` takes a base store and returns a wrapped store (e.g. one that
+    virtualizes OME-TIFF data as zarr).
+    """
+    _STORE_EXTENSION_APPLIERS[extension] = applier
+
+
+def store_metadata_to_instance(info: dict):
+    """Construct a concrete zarr-python store instance from ``ZarrStoreInfo`` metadata.
+
+    The inverse of :func:`store_instance_to_metadata`:
+
+      - ``HttpStore`` -> a remote fsspec-backed store for the URL;
+      - ``LocalStore`` -> a ``zarr.storage.LocalStore`` for the path;
+      - ``MemoryStore`` -> raises (an in-memory store has no portable
+        representation and must be provided directly).
+
+    Any ``store_extensions`` are then applied outermost-last using appliers
+    registered via :func:`register_store_extension`.
+    """
+    store_type = info["store_type"]
+    params = info.get("store_params") or {}
+
+    if store_type == "HttpStore":
+        store = http_store_from_url(params["url"])
+    elif store_type == "LocalStore":
+        from zarr.storage import LocalStore
+        store = LocalStore(params["path"])
+    elif store_type == "MemoryStore":
+        raise ValueError(
+            "Cannot reconstruct an in-memory store from metadata "
+            f"({params.get('message')!r}); provide the store instance directly."
+        )
+    else:
+        raise ValueError(f"Unknown store_type: {store_type!r}")
+
+    for ext in info.get("store_extensions") or []:
+        applier = _STORE_EXTENSION_APPLIERS.get(ext)
+        if applier is None:
+            raise ValueError(
+                f"No applier registered for store extension {ext!r}. "
+                "Register one via register_store_extension()."
+            )
+        store = applier(store)
+    return store
+
+
+def http_store_from_url(url: str):
+    """Construct a remote (fsspec-backed) zarr store from a URL."""
+    from obstore.store import HTTPStore
+    from zarr.storage import ObjectStore
+
+    obs_store = HTTPStore.from_url(url)
+    return ObjectStore(obs_store, read_only=True)
+
+
+def _derive_store_url(store):
+    """Best-effort extraction of a URL from a remote obstore-backed zarr store."""
+    # zarr.storage.ObjectStore's .store should contain an obstore HTTPStore.
+    obs_store = getattr(store, "store", None)
+    url = getattr(obs_store, "url", None)
+    if isinstance(url, str) and "://" in url:
+        return url
+    return None