WEBKNOSSOS SAM Adapter

This project adds grayscale Segment Anything quick select support to a stock self-hosted WEBKNOSSOS deployment.

It exposes the binary endpoint that WEBKNOSSOS expects at /predictions/sam2_hiera_b and can either:

• run real SAM 2 inference on an NVIDIA GPU, or
• fall back to a simple heuristic mode for protocol testing.

Features

• Flask-based standalone service
• Binary request parsing compatible with WEBKNOSSOS quick select
• Grayscale-only MVP
• Point and bounding-box prompts
• Multi-slice requests up to depth 50
• Health endpoint at /healthz
• Optional heuristic fallback for smoke tests

Supported element classes

• uint8
• uint16
• uint32
• int8
• int16
• int32
• float32 (requires intensity range)
• float64 (requires intensity range)

Not supported in this MVP:

• uint24 (RGB)
• uint64
• int64

Environment variables

• SAM_ADAPTER_INFERENCE_MODE: sam2 or heuristic (default: sam2)
• SAM_ADAPTER_ALLOW_FALLBACK: true/false (default: true)
• SAM2_CHECKPOINT: path to the SAM 2 checkpoint file
• SAM2_MODEL_CONFIG: path or package config for the model yaml
• SAM2_DEVICE: device string, usually cuda
• SAM_ADAPTER_MASK_THRESHOLD: mask threshold before binarization (default: 0.0)

Local run

python -m venv .venv
. .venv/bin/activate
pip install -r sam_adaper/requirements.txt
python -m sam_adaper.app

Docker run

cd /mnt/c/code
docker build -t webknossos-sam-adapter -f sam_adaper/Dockerfile sam_adaper
docker run --rm -p 8080:8080 \
  --gpus all \
  -e SAM2_CHECKPOINT=/models/sam2_hiera_base_plus.pt \
  -v $(pwd)/models:/models:ro \
  webknossos-sam-adapter

Docker Compose run

The adapter repo includes its own standalone Compose file so you can boot and test it independently of WEBKNOSSOS first.

cd /mnt/c/code/sam_adaper
docker compose up -d --build
curl http://localhost:8080/healthz

For a protocol-only smoke test without model weights, start it in heuristic mode:

cd /mnt/c/code/sam_adaper
SAM_ADAPTER_INFERENCE_MODE=heuristic docker compose up -d --build

WEBKNOSSOS wiring

This project includes its own WEBKNOSSOS overlay compose file so the webknossos repo does not need to be modified.

Then start your stack with:

cd /mnt/c/code/sam_adaper
PUBLIC_HOST=your-host.example LETSENCRYPT_EMAIL=you@example.com \
docker compose \
  -f ../webknossos/tools/hosting/docker-compose.yml \
  -f docker-compose.webknossos.yml \
  up -d

The overlay uses both gpus: all and a deploy.resources.reservations.devices block so it works with current Docker Compose v2 setups and also remains compatible with environments that only honor one of those mechanisms.

Validation flow

1. curl http://localhost:8080/healthz
2. Open a grayscale 3D dataset in WEBKNOSSOS.
3. Switch to the quick select tool.
4. Use point prompt.
5. Use bounding-box prompt.

If you need to debug request parsing before real model setup, use SAM_ADAPTER_INFERENCE_MODE=heuristic.

Heuristic smoke test

1. Start the adapter on its own:

   cd /mnt/c/code/sam_adaper
   SAM_ADAPTER_INFERENCE_MODE=heuristic docker compose up -d --build

2. Confirm the adapter is healthy:

   curl http://localhost:8080/healthz

3. Stop the standalone adapter so the WEBKNOSSOS overlay can reuse port 8080 cleanly:

   cd /mnt/c/code/sam_adaper
   docker compose down

4. Start WEBKNOSSOS with the Segment Anything overlay from the adapter directory:

   cd /mnt/c/code/sam_adaper
   PUBLIC_HOST=your-host.example LETSENCRYPT_EMAIL=you@example.com \
   SAM_ADAPTER_INFERENCE_MODE=heuristic docker compose \
     -f ../webknossos/tools/hosting/docker-compose.yml \
     -f docker-compose.webknossos.yml \
     up -d --build

5. Open a grayscale 3D dataset and switch to quick select.

6. Click once on a structure. In heuristic mode you should get a small circular mask.

7. Drag a rectangle. In heuristic mode you should get the rectangle area filled.

If those two behaviors work, the request/response protocol and WEBKNOSSOS wiring are correct. You can then switch back to SAM_ADAPTER_INFERENCE_MODE=sam2 and add real model weights.