copick-web

Web-based visualization tool for cryoET data using the copick data model.

Overview

copick-web consists of two components:

• Server: Python FastAPI server that provides a REST API for copick metadata and proxies zarr data
• Client: React/TypeScript application using idetik-react for OME-Zarr visualization

Features

• Browse copick runs, voxel spacings, and tomograms
• View tomogram slices with channel controls and scale bar
• Linked XY / XZ / YZ orthoslices with crosshairs and a 3D volume view (or a single plane), panes toggleable
• Display particle picks as point overlays (dots or physical radius shells), coloured per instance ID for filament objects
• Filaments (ordered centrelines) drawn as dense points, coloured per filament ID
• Segmentation overlays: binary, multilabel, instance (shared instance palette, click to identify, instance browser) and panoptic (objects / instances / both)
• Newer copick features (filaments, instance and panoptic segmentations) are detected at runtime; older copick versions keep working

Prerequisites

• Python 3.9+
• Node.js 20.19.0+
• A copick configuration file pointing to your data

Quick Start

Installation

# Install the server package
cd server
pip install -e .

# Build the client
cd ../client
npm install
npm run build:server

Running

# Start copick-web with your config file
copick-web /path/to/your/copick_config.json

This will start the server and open your browser to http://localhost:8000

CLI Options

copick-web CONFIG [OPTIONS]

Options:
  --host TEXT     Host to bind to (default: 127.0.0.1)
  --port INTEGER  Port to bind to (default: 8000)
  --no-browser    Don't open browser automatically
  --base-path TEXT  URL prefix of a proxy that forwards the full path (env: BASE_PATH)
  --help          Show this message and exit.

Examples:
  copick-web config.json                    # Start with defaults
  copick-web config.json --port 9000        # Custom port
  copick-web config.json --no-browser       # Don't auto-open browser

Behind a proxy (e.g. Open OnDemand)

The client finds its URL prefix at runtime from the page it was loaded from, so the same install works under any prefix — for example a different /rnode/<host>/<port>/ for every node and port an HPC job lands on. Open the URL with its trailing slash.

• The proxy strips the prefix (Open OnDemand's /rnode/<host>/<port>/): nothing to set.

  copick-web config.json --host 0.0.0.0 --port "$port" --no-browser
  # open https://ondemand.example.org/rnode/$(hostname)/$port/

• The proxy forwards the full path (Open OnDemand's /node/<host>/<port>/): pass the prefix with --base-path (or BASE_PATH). Requests with or without it are served alike.

  copick-web config.json --host 0.0.0.0 --port "$port" --no-browser --base-path "/node/$(hostname)/$port"

Development

We offer dev containers for ease of use or manual dev setups.

Docker/Podman Compose

Pre-requisites: Podman (recommended) or Docker installed with Compose extension. Check if installed with docker-compose version or podman compose version

• create .env file using .env.example as template.
• obtain or use a copick project. Modify config.json's overlay_root parameter to local:/data/copick_data/

# Example .env
# Host ports exposed by the containers
SERVER_HOST_PORT=8880
CLIENT_HOST_PORT=5180

# Please modify below with path to copick project, pointing to the copick config json.
# NOTE: In the config.json, please change "overlay_root": "local:/data/copick_data/"
# The config gets mounted read-only into the container at /data/copick_config.json.
COPICK_CONFIG_PATH=.scratch/NPC1_DEMO/configNPC1.json

# Path to your copick data directory on the host machine.
# This gets mounted into the container at /data/copick_data.
# Make sure paths inside your copick config reference /data/copick_data.
COPICK_DATA_DIR=.scratch/NPC1_DEMO/NPC1_DEMO/project

Starting the servers

# start frontend and backend
podman compose -f compose-dev.yml up
# when done developing, shutdown with ctrl+c or
podman compose -f compose-dev.yml down

Runs both server and client with hot reload, refreshing on code updates. Access on http://localhost:8880 or specified SERVER_HOST_PORT

Access backend API (FastAPI) with http://localhost:8880/docs

To build & check production images

# uses compose.yml
podman compose up --build -d
# when done developing, shutdown
podman compose down

Manual

If you do not wish to run on Docker, these are the manual steps. Please see prerequisites section.

Server Development

cd server
pip install -e ".[dev]"

# Run with uvicorn for hot-reload
export COPICK_CONFIG_PATH=/path/to/config.json
uvicorn copick_web.app.main:app --reload --port 8000

Client Development

cd client
npm install
npm run dev  # Starts Vite dev server at localhost:5173

When developing the client, run the server separately and the Vite dev server will proxy API requests.

Code Quality

# Server
cd server
black src/
ruff check src/

# Client
cd client
npm run lint
npm run format

Configuration

Environment Variables

Variable	Default	Description
COPICK_CONFIG_PATH	copick_config.json	Path to copick configuration file
CORS_ORIGINS	["http://localhost:5173", "http://localhost:8000"]	Allowed CORS origins
HOST	0.0.0.0	Server host
PORT	8000	Server port

Create a .env file in the server/ directory to set these values.

API Endpoints

Metadata

• GET /api/config - Project configuration
• GET /api/objects - Pickable objects
• GET /api/runs - List of runs
• GET /api/runs/{run} - Run details with voxel spacings
• GET /api/runs/{run}/picks - List of picks for a run
• GET /api/runs/{run}/picks/{obj}/{user}/{session} - Pick points
• GET /api/runs/{run}/segmentations - List of segmentations (with segmentation_type; filter with ?segmentation_type=)
• GET /api/runs/{run}/segmentations/{type}/{name}/{user}/{session}/{vs}/instances?level=1 - Instance voxel counts and centroids (instance / panoptic)
• GET /api/runs/{run}/filaments - Filament sets (empty on a copick without filaments)
• GET /api/runs/{run}/filaments/{obj}/{user}/{session} - Filament centrelines (501 on a copick without filaments)

Zarr Proxy

• GET /zarr/tomo/{run}/{vs}/{type}/{path} - Tomogram zarr chunks
• GET /zarr/segmentation/{type}/{run}/{name}/{user}/{session}/{vs}/{path} - Segmentation zarr chunks (type: binary, multilabel, instance, panoptic)
• GET /zarr/seg/{run}/{name}/{user}/{session}/{vs}/{path} - Legacy alias (binary and multilabel only)

Architecture

copick-web/
├── server/                     # FastAPI server package
│   ├── pyproject.toml          # Package config with CLI entry point
│   └── src/copick_web/
│       ├── cli.py              # CLI entry point
│       ├── static/             # Built client files
│       └── app/
│           ├── main.py         # FastAPI application
│           ├── config.py       # Settings
│           ├── models.py       # Pydantic response models
│           ├── routes/         # API route handlers
│           └── services/       # Business logic (CopickService)
└── client/                     # React application
    └── src/
        ├── api/                # API client and hooks
        ├── components/         # React components
        │   ├── layout/         # App layout
        │   ├── navigation/     # Run tree
        │   ├── entities/       # Picks/segmentations tables
        │   ├── viewer/         # Tomogram viewer
        │   └── overlays/       # Picks/segmentation overlays
        └── contexts/           # React context providers

License

MIT