copick-web 0.1.5__py3-none-any.whl

copick_web/__init__.py

@@ -0,0 +1,3 @@
+"""Copick Web - Web visualization for copick datasets."""
+
+__version__ = "0.1.5"

copick_web/app/__init__.py

@@ -0,0 +1 @@
+# copick-web server app

copick_web/app/config.py

@@ -0,0 +1,52 @@
+"""Server configuration using pydantic-settings."""
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    copick_config_paths: list[str] = []
+    registry_url: str | None = None
+    registry_refresh_seconds: int = 60
+    service_cache_size: int = 8
+    # Hard ceiling on a single zarr-chunk read. If exceeded, the request
+    # returns 504 and the underlying CopickService is evicted so the next
+    # request rebuilds with a fresh SSH connection.
+    zarr_read_timeout_seconds: float = 60.0
+    # Max concurrent zarr chunk reads per project. Bounds peak memory
+    # (≈ value × max_chunk_size) and avoids saturating a single asyncssh
+    # SFTP channel — past ~16 in flight, parallel reads stop helping.
+    zarr_concurrency_per_project: int = 8
+    slurm_user: str | None = None
+    slurm_keyfile: str | None = None
+    slurm_ssh_port: int = 22
+    # cluster_id -> SSH hostname/IP. Defaults mirror the umbrella seed
+    # (umbrella/stores/migrations/0010_seed_clusters.py). Override via env:
+    #   CLUSTER_HOSTS='{"bruno":"…","czii":"…"}'
+    cluster_hosts: dict[str, str] = {
+        "bruno": "192.168.98.229",
+        "czii": "10.50.120.90",
+    }
+    cors_origins: list[str] = [
+        "http://localhost:5173",
+        "http://127.0.0.1:5173",
+        "http://localhost:8000",
+        "http://127.0.0.1:8000",
+    ]
+    host: str = "0.0.0.0"
+    port: int = 8000
+    base_path: str = ""
+    # In-memory caches of derived data (env: THUMBNAIL_CACHE_MB, MEASUREMENT_CACHE_MB, CACHE_MAX_AGE_SECONDS,
+    # CACHE_SWEEP_SECONDS). Entries older than the max age are dropped by a sweep every CACHE_SWEEP_SECONDS.
+    thumbnail_cache_mb: int = 64
+    measurement_cache_mb: int = 512
+    cache_max_age_seconds: int = 3600
+    cache_sweep_seconds: int = 300
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+
+
+settings = Settings()

copick_web/app/dependencies.py

@@ -0,0 +1,38 @@
+"""FastAPI dependency injection for project-scoped routes."""
+
+from fastapi import HTTPException, Path
+
+from .models import ProjectSummaryResponse
+from .services.copick_service import CopickService
+from .services.project_registry import ProjectRegistry, get_project_registry
+from .services.registry_client import RegistryError
+
+
+def get_registry() -> ProjectRegistry:
+    """Dependency: the application's ``ProjectRegistry``."""
+    return get_project_registry()
+
+
+def get_copick_service(project_id: str = Path(...)) -> CopickService:
+    """Dependency: resolve the ``CopickService`` for the path's ``project_id``."""
+    registry = get_project_registry()
+    try:
+        return registry.get_service(project_id)
+    except KeyError:
+        raise HTTPException(status_code=404, detail=f"Project '{project_id}' not found") from None
+    except RegistryError as e:
+        raise HTTPException(status_code=502, detail=str(e)) from e
+
+
+def get_project_meta(project_id: str = Path(...)) -> ProjectSummaryResponse:
+    """Dependency: resolve the ``ProjectSummaryResponse`` for the path's ``project_id``.
+
+    Used by routes that need to branch on ``source`` (local vs. registry) — e.g.
+    zarr URL construction, where registry projects skip the server-side proxy
+    and point the browser at ``data_url`` directly.
+    """
+    registry = get_project_registry()
+    try:
+        return registry.get_metadata(project_id)
+    except KeyError:
+        raise HTTPException(status_code=404, detail=f"Project '{project_id}' not found") from None

copick_web/app/main.py

@@ -0,0 +1,180 @@
+"""FastAPI application entry point."""
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+
+from .config import settings
+from .routes import config, filaments, projects, runs, zarr_proxy
+from .services.project_registry import ProjectRegistry, set_project_registry
+from .services.registry_client import RegistryClient
+
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+
+async def _refresh_loop(registry: ProjectRegistry, interval: int):
+    """Background loop that refreshes the registry list at a fixed cadence."""
+    while True:
+        try:
+            await asyncio.sleep(interval)
+            await registry.refresh_registry()
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.exception("Registry refresh loop error: %s", e)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan handler."""
+    # Build registry
+    if not settings.copick_config_paths and not settings.registry_url:
+        raise RuntimeError(
+            "No project source configured. Provide local config paths via the CLI / "
+            "COPICK_CONFIG_PATHS, or set REGISTRY_URL."
+        )
+
+    client = RegistryClient(settings.registry_url) if settings.registry_url else None
+    registry = ProjectRegistry(registry_client=client, service_cache_size=settings.service_cache_size)
+
+    for path in settings.copick_config_paths:
+        try:
+            pid = registry.register_local(path)
+            logger.info(
+                "Registered local project '%s' (%s) from %s",
+                pid,
+                registry.get_metadata(pid).name or "unnamed",
+                path,
+            )
+        except FileNotFoundError as e:
+            logger.error("Local config not found, skipping: %s (%s)", path, e)
+
+    if client is not None:
+        try:
+            await registry.refresh_registry()
+        except Exception as e:
+            logger.warning("Initial registry refresh failed; continuing without registry projects: %s", e)
+
+    set_project_registry(registry)
+
+    tasks = [asyncio.create_task(_sweep_caches(registry, settings.cache_sweep_seconds))]
+    if client is not None:
+        tasks.append(asyncio.create_task(_refresh_loop(registry, settings.registry_refresh_seconds)))
+
+    logger.info("copick-web ready: %d project(s) listed.", len(registry.list_projects()))
+
+    try:
+        yield
+    finally:
+        for task in tasks:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+        logger.info("Shutting down copick-web server")
+
+
+async def _sweep_caches(registry: ProjectRegistry, every: float) -> None:
+    """Drop expired cache entries of every open project regularly, so memory is released even when nothing is
+    requested."""
+    while True:
+        await asyncio.sleep(max(every, 1))
+        try:
+            dropped = registry.sweep_caches()
+            if dropped:
+                logger.info(f"Dropped {dropped} expired cache entries")
+        except Exception as e:  # never let the sweeper die
+            logger.warning(f"Cache sweep failed: {e}")
+
+
+app = FastAPI(
+    title="Copick Web Server",
+    description="API server for copick web visualization",
+    version="0.1.0",
+    lifespan=lifespan,
+    # A prefix the proxy forwards (e.g. /node/<host>/<port>); requests with or without it are routed alike.
+    root_path=settings.base_path.rstrip("/"),
+)
+
+
+@app.middleware("http")
+async def redirect_root_relatively(request: Request, call_next):
+    """Add the trailing slash to the app root under a forwarded prefix (``/node/<host>/<port>``) with a relative
+    redirect: Starlette's own is absolute and names the Host it was sent, which may be the backend behind the proxy."""
+    root = request.scope.get("root_path", "")
+    if root and request.url.path == root:
+        query = f"?{request.url.query}" if request.url.query else ""
+        return RedirectResponse(f"{root.rsplit('/', 1)[-1]}/{query}", status_code=307)
+    return await call_next(request)
+
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(projects.router)
+app.include_router(config.router)
+app.include_router(runs.router)
+app.include_router(filaments.router)
+app.include_router(zarr_proxy.router)
+
+
+@app.get("/health")
+async def health_check():
+    """Liveness check. Async so a saturated threadpool can't make the server look dead."""
+    return {"status": "healthy"}
+
+
+# Serve the built SPA. Order matters: SPA catch-all must come BEFORE the
+# StaticFiles mount at "/" so it can intercept deep-link refreshes
+# (e.g. /projects/abc) and return index.html instead of 404.
+static_dir = Path(__file__).parent.parent / "static"
+
+
+def _has_static_files() -> bool:
+    if not static_dir.exists():
+        return False
+    return any(f.name != ".gitkeep" for f in static_dir.iterdir())
+
+
+if _has_static_files():
+    index_file = static_dir / "index.html"
+
+    @app.get("/projects/{full_path:path}", include_in_schema=False)
+    def spa_projects(full_path: str, request: Request):
+        """Serve the SPA index.html for client-side routes under /projects."""
+        if not index_file.exists():
+            raise HTTPException(status_code=404, detail="SPA index.html missing")
+        return FileResponse(index_file)
+
+    logger.info(f"Serving static files from: {static_dir}")
+    app.mount("/", StaticFiles(directory=static_dir, html=True), name="static")
+elif static_dir.exists():
+    logger.warning(
+        f"Static directory exists but is empty: {static_dir}. "
+        "Run 'npm run build:server' in the client directory to build the client."
+    )
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "copick_web.app.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=True,
+    )

copick_web/app/models.py

@@ -0,0 +1,370 @@
+"""Pydantic response models for the API."""
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel
+
+SegmentationType = Literal["binary", "multilabel", "instance", "panoptic"]
+
+
+class FeaturesResponse(BaseModel):
+    """Optional features of the installed copick (see services/compat.py)."""
+
+    filaments: bool = False
+    segmentation_types: bool = False
+    pick_identity: bool = False
+
+
+class ProjectSummaryResponse(BaseModel):
+    """Summary of a project tracked by the project registry."""
+
+    id: str
+    source: Literal["registry", "local"]
+    # Registry-derived fields (all optional — locals don't have them).
+    session_name: Optional[str] = None
+    run_name: Optional[str] = None
+    cluster_id: Optional[str] = None
+    scope: Optional[str] = None
+    status: Optional[str] = None
+    created_at: Optional[str] = None
+    proc_run_id: Optional[int] = None
+    config_url: Optional[str] = None
+    data_url: Optional[str] = None
+    root_url: Optional[str] = None
+    # Pulled from copick config when service is materialized; nullable so listing stays cheap.
+    name: Optional[str] = None
+    description: Optional[str] = None
+
+
+class ConfigResponse(BaseModel):
+    """Project configuration response."""
+
+    name: Optional[str]
+    description: Optional[str]
+    version: Optional[str]
+    user_id: Optional[str]
+    session_id: Optional[str]
+    features: FeaturesResponse = FeaturesResponse()
+
+
+class PickableObjectResponse(BaseModel):
+    """Pickable object metadata."""
+
+    name: str
+    is_particle: bool
+    label: Optional[int]
+    color: tuple[int, int, int, int]
+    radius: Optional[float]
+    is_filament: bool = False
+    filament: Optional[dict[str, Any]] = None
+
+
+class FilamentSpecModel(BaseModel):
+    """Filament declaration of an object (copick ``FilamentSpec``)."""
+
+    polar: Optional[bool] = None
+    helical_rise_a: Optional[float] = None
+    helical_twist_deg: Optional[float] = None
+
+
+class ObjectTypeFields(BaseModel):
+    """The editable fields of a pickable object type."""
+
+    name: str
+    is_particle: bool = True
+    label: Optional[int] = None
+    color: tuple[int, int, int, int]
+    radius: Optional[float] = None
+    map_threshold: Optional[float] = None
+    emdb_id: Optional[str] = None
+    pdb_id: Optional[str] = None
+    identifier: Optional[str] = None
+    #: None: not a filament.
+    filament: Optional[FilamentSpecModel] = None
+
+
+class ObjectTypeRequest(ObjectTypeFields):
+    """Create or update an object type; ``version`` is the object list version the change was made against."""
+
+    version: str
+
+
+class ObjectTypesResponse(BaseModel):
+    """The configuration's object types, for editing."""
+
+    version: str
+    editable: bool
+    config_file: Optional[str]
+    suggested_label: int
+    objects: list[ObjectTypeFields]
+
+
+class ReloadResponse(BaseModel):
+    """The project after it was re-opened from its configuration file."""
+
+    runs: int
+
+
+class RunSummaryResponse(BaseModel):
+    """Summary of a run."""
+
+    name: str
+
+
+class TomogramSummaryResponse(BaseModel):
+    """Summary of a tomogram."""
+
+    tomo_type: str
+
+
+class VoxelSpacingSummaryResponse(BaseModel):
+    """Summary of a voxel spacing with its tomograms."""
+
+    voxel_size: float
+    tomograms: list[TomogramSummaryResponse]
+
+
+class RunDetailResponse(BaseModel):
+    """Detailed run information including voxel spacings."""
+
+    name: str
+    voxel_spacings: list[VoxelSpacingSummaryResponse]
+
+
+class ZarrInfo(BaseModel):
+    shape: list[int]
+    dtype: str
+    levels: int
+
+
+class TomogramInfo(BaseModel):
+    tomo_type: str
+    #: Where the tomogram is read from (portal location, overlay or static copy).
+    path: Optional[str] = None
+    #: Level-0 shape (z, y, x), dtype and pyramid levels; None if the store could not be read.
+    zarr: Optional[ZarrInfo] = None
+    #: CryoET Data Portal metadata (id, url, name, reconstruction, deposition, authors, paths...), if any.
+    portal: Optional[dict[str, Any]] = None
+
+
+class VoxelSpacingInfo(BaseModel):
+    voxel_size: float
+    static_path: Optional[str] = None
+    overlay_path: Optional[str] = None
+    portal_id: Optional[int] = None
+    tomograms: list[TomogramInfo]
+
+
+class RunPortalInfo(BaseModel):
+    run_id: int
+    run_name: Optional[str] = None
+    run_url: str
+    dataset_id: Optional[int] = None
+    dataset_url: Optional[str] = None
+
+
+class RunInfoResponse(BaseModel):
+    """Where a run's data lives and what it holds (the run info dialog)."""
+
+    name: str
+    backend: str
+    static_path: Optional[str] = None
+    overlay_path: Optional[str] = None
+    portal: Optional[RunPortalInfo] = None
+    counts: dict[str, Optional[int]]
+    voxel_spacings: list[VoxelSpacingInfo]
+
+
+class TomogramResponse(BaseModel):
+    """Tomogram with zarr URL."""
+
+    tomo_type: str
+    zarr_url: str
+
+
+class PointResponse(BaseModel):
+    """A single pick point.
+
+    ``x``, ``y``, ``z`` are the stored location in Angstrom. The particle centre is the location plus the translation
+    of ``transformation`` (a 4x4 object-to-tomogram matrix); clients draw the centre and send the location and
+    transformation back unchanged when saving.
+    """
+
+    x: float
+    y: float
+    z: float
+    instance_id: Optional[int]
+    score: Optional[float]
+    transformation: Optional[list[list[float]]] = None
+
+
+class PicksSummaryResponse(BaseModel):
+    """Summary of a picks collection."""
+
+    object_name: str
+    user_id: str
+    session_id: str
+    point_count: int
+    color: tuple[int, int, int, int]
+    is_filament: bool = False
+    instance_count: int = 0
+
+
+class PicksDetailResponse(BaseModel):
+    """Detailed picks with all points."""
+
+    object_name: str
+    user_id: str
+    session_id: str
+    color: tuple[int, int, int, int]
+    points: list[PointResponse]
+    is_filament: bool = False
+
+
+class SegmentationSummaryResponse(BaseModel):
+    """Summary of a segmentation."""
+
+    name: str
+    user_id: str
+    session_id: str
+    voxel_size: float
+    is_multilabel: bool
+    zarr_url: str
+    color: Optional[tuple[int, int, int, int]]
+    segmentation_type: SegmentationType = "binary"
+    is_instance: bool = False
+    is_panoptic: bool = False
+    channels: Optional[list[str]] = None
+
+
+class InstanceResponse(BaseModel):
+    """One instance (or panoptic segment) of a segmentation, measured on a pyramid level."""
+
+    instance_id: int
+    label: Optional[int] = None
+    voxel_count: int
+    centroid: tuple[float, float, float]
+
+
+class InstancesResponse(BaseModel):
+    """The instances of an instance or panoptic segmentation."""
+
+    segmentation_type: SegmentationType
+    level: int
+    voxel_size: float
+    instances: list[InstanceResponse]
+
+
+# --- Filaments ---
+
+
+class FilamentCurveModel(BaseModel):
+    """An editable or fitted filament curve (copick ``CopickFilamentCurve``); ``points`` are regenerated from it."""
+
+    kind: str
+    control_points: list[tuple[float, float, float]]
+    step: float
+    alpha: Optional[float] = None
+    degree: Optional[int] = None
+    knots: Optional[list[float]] = None
+    smoothing: Optional[float] = None
+
+
+class FilamentResponse(BaseModel):
+    """One traced filament: its ordered centreline in Angstrom."""
+
+    instance_id: int
+    points: list[tuple[float, float, float]]
+    polarity_known: bool = False
+    score: float = 1.0
+    radius: Optional[float] = None
+    curve_kind: Optional[str] = None
+    #: The stored curve, if any (it may be stale: editors check it against ``points``).
+    curve: Optional[FilamentCurveModel] = None
+    metadata: dict[str, Any] = {}
+
+
+class FilamentsSummaryResponse(BaseModel):
+    """Summary of a set of filaments (one object, user and session)."""
+
+    object_name: str
+    user_id: str
+    session_id: str
+    filament_count: int
+    color: tuple[int, int, int, int]
+    instance_ids: list[int] = []
+
+
+class FilamentsDetailResponse(BaseModel):
+    """A set of filaments with their centrelines."""
+
+    object_name: str
+    user_id: str
+    session_id: str
+    color: tuple[int, int, int, int]
+    filaments: list[FilamentResponse]
+    voxel_spacing: Optional[float] = None
+
+
+class FilamentWriteModel(BaseModel):
+    """One filament to store: a ``curve`` (its points are regenerated by copick) or, for filaments without one,
+    the ``points`` as they are."""
+
+    instance_id: int
+    curve: Optional[FilamentCurveModel] = None
+    points: Optional[list[tuple[float, float, float]]] = None
+    polarity_known: bool = False
+    score: float = 1.0
+    radius: Optional[float] = None
+    metadata: dict[str, Any] = {}
+
+
+class SaveFilamentsRequest(BaseModel):
+    """Replace a filament set (created if missing). With ``pick_spacing`` (Angstrom), picks sampled along the
+    filaments replace the picks set of the same object, user and session."""
+
+    filaments: list[FilamentWriteModel]
+    voxel_spacing: Optional[float] = None
+    pick_spacing: Optional[float] = None
+
+
+class SaveFilamentsResponse(BaseModel):
+    filaments: FilamentsDetailResponse
+    n_picks: int = 0
+
+
+# --- Request models for picks mutations ---
+
+
+class CreatePicksRequest(BaseModel):
+    """Request to create a new picks collection."""
+
+    object_name: str
+    user_id: str
+    session_id: str
+
+
+class PointRequest(BaseModel):
+    """Point for create/update operations."""
+
+    x: float
+    y: float
+    z: float
+    instance_id: Optional[int] = None
+    score: Optional[float] = 1.0
+    transformation: Optional[list[list[float]]] = None
+
+
+class UpdatePicksRequest(BaseModel):
+    """Request to update picks points."""
+
+    points: list[PointRequest]
+
+
+class CreatePicksResponse(BaseModel):
+    """Response after creating picks."""
+
+    object_name: str
+    user_id: str
+    session_id: str
+    color: tuple[int, int, int, int]

copick_web/app/routes/__init__.py

@@ -0,0 +1 @@
+# API routes