Spinal Tap is a Dash application that provides simple visualization tools for the Scalable Particle Imaging With Neural Embeddings (SPINE) package.

The standard installation and container remain lean and read SPINE HDF5 files. An optional LArCV container adds ROOT, LArCV2, and maintained spine-prod detector conversion bundles so raw LArCV ROOT files can be visualized directly.

Installation

You can install Spinal Tap and all dependencies (including Dash, Flask, Plotly, and spine) using pip:

pip install .

Or, for editable development mode:

pip install -e .

Usage

Launch the application and open http://localhost:8888 in a browser:

spinal-tap

Check the installed version with:

spinal-tap --version

Spinal Tap provides fast WebGL and Plotly renderers, reconstruction/truth comparison, object filtering and inspection, configurable appearance, and portable exports. The complete user guide covers:

• opening files, manifests, uploads, URLs, and shared views,
• display controls and object inspection,
• appearance and camera controls, and
• sharing and export formats.

See the Spinal Tap documentation for the full installation, usage, deployment, and development guides.

Deployment

Kubernetes

Spinal Tap is deployed on SLAC's S3DF Kubernetes infrastructure and is accessible at:

https://spinal-tap.slac.stanford.edu

S3DF input paths may use either the host form /sdf/data/neutrino/... or the container form /data/...; Spinal Tap resolves both forms automatically.

Readers and built events are cached per application process. The bounds can be configured with SPINAL_TAP_READER_CACHE_SIZE (default 8) and SPINAL_TAP_EVENT_CACHE_SIZE (default 2); set either to 0 to disable that cache. Compact binary scenes are held in an eight-entry process-local LRU while the browser fetches them; configure this bound with SPINAL_TAP_SCENE_CACHE_SIZE (minimum 1).

The Kubernetes configuration files are located in the k8s/ directory. For deployment instructions and SLAC-specific configuration details, see:

• k8s/README.md - Deployment guide
• k8s/SLAC_CONFIG.md - Detailed SLAC S3DF configuration

Docker

Docker images are automatically built and published to GitHub Container Registry when version tags are pushed:

docker pull ghcr.io/deeplearnphysics/spinal-tap:latest

Use the separate LArCV flavor only when direct ROOT input is needed:

docker pull ghcr.io/deeplearnphysics/spinal-tap:larcv

To run locally with Docker:

docker run -p 8888:8888 ghcr.io/deeplearnphysics/spinal-tap:latest

For LArCV input, run the LArCV image, mount the source data, and select the matching dated detector converter in the Data panel:

docker run --rm -p 8888:8888 -v /host/data:/data:ro \
  ghcr.io/deeplearnphysics/spinal-tap:larcv

Development & CI/CD

• Code style is enforced with black, isort, and flake8 (pre-commit and CI).
• The GitHub Actions workflow builds and tests on every commit, PR, tag, and release.
• The complete test suite enforces 100% statement coverage and publishes its report to Codecov.
• Docker images are built automatically on version tag pushes (e.g., v0.1.2).
• Publishing:
  • On tag push: publishes to Test PyPI (requires TEST_PYPI_API_TOKEN secret).
  • On GitHub Release: publishes to PyPI (requires PYPI_API_TOKEN secret).